[Bf-docboard] Manual Formatting Discussion

[Fade]

Hi all,

I thought it would be best to break this out into a separate thread for 
ease of use.

For anyone picking this up now, the discussion pertains to specifically 
improving manual formatting and increasing consistency when using 
formatting elements (headings, lists) across pages. Issues are mentioend 
immediately below, suggestions are further down.

kesten previously mentioned a committee for working on the formatting 
tests, given the responses on the board so far, I'll suggest that this 
committee be: kesten, cal, jared, greylica and me. Jared and I have 
already prepared some mockups (linked at the end of this post). If 
everyone is ok with this I suggest the following timetable/process:

1. Decide on the skin (2 weeks from now)
2. Mockups with new/edited/current skin (4 weeks from now).

Would a weekly meeting in #blenderwiki work best for everyone? Or mail 
to the board? If we prefer #blenderwiki can you let us know what 
timezone you're in so we can work out a decent day/time (I'm in 
Australia with UTC+10).

----Current formatting issues----

--1. Inconsistent style (headings, lists)--

This includes but is not limited to: when and how often to use H2, H3 etc.
What determines whether a list should be bulleted or numbered?
What format should definition lists take?

--2. Suitability of Naid skin as the default.--

Performance issues
Do the right and left columns serve a useful purpose?
Why are headers and footers no longer displayed?

I regularly find that pages with the default Naid Skin load noticeably 
slower. Without specific testing, this appears to be due to the menus on 
the left hand side and on the main wiki page. After changing to a skin 
that doesn't have the drop down/roll out effect, page loading is much 
quicker. The left hand column is really only useful if you know where 
you want to go and even then it is quicker to jump back to the main page 
and go from there. I find the content in the the right hand column 
useful (if only for being able to link to specific sections from other 
pages), but agree that with the overuse of headings, it can quickly 
become unwieldy.

--3. Mobile devices--

How to fix the extensive scrolling required to view pages due to lack of 
word wrapping?

--4. General aesthetics--

Would useability be improved with redesigned info boxes?
Do UI items need different weighting?
Are links visible enough?
Are the size of headings appropriate?


----Suggestions----

1.
 From Jared
One =heading 1= per page, as recommended in the Mediawiki documentation
Describe UI items/options with a clear separation between the word and 
the description
Term on its own line, and the decsriptions on next line, indented - *Not 
bulleted*. Visually interferes with the word itself, and is consistent 
with most of the manual and other manuals - Bullets are only for 
examples/lists of things
Numbered lists for explanation of steps
Omit unnecessary sub-headings, like ==Description==. (It should be 
assumed that what is written is a description).

2.

Switch to a new default skin. My preference would be for either the 
Blender or Vector skin.
If we stick with Naid, remove the left hand menu. Move the right menu to 
the left or the top (similar to a standard wikipedia page with a 
contents box)

3.

No idea about this one, I don't know much about mobile devices :-)

4.
 From Jared
Literals: UI items should be *bold, *or *bold+italic*).
Bold stands out better than *italic *alone
Links: brighter blue to help them stand out Indent text/headings under 
==heading 2== to better separate sections.
Increase size of ==heading 2== to make it more separate from ===heading 
3===
Add a bar/background color to headings ?

----Current Mockups----

 From Jared: http://www.artofjared.com/content/wikiFormatting.html

Mockups from me.

http://wiki.blender.org/index.php/User:Fade/Doc:2.6/format_test1
http://wiki.blender.org/index.php/User:Fade/Doc:2.6/format_test2
http://wiki.blender.org/index.php/User:Fade/Doc:2.6/format_test3
http://wiki.blender.org/index.php/User:Fade/Doc:2.6/format_test4


-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.blender.org/pipermail/bf-docboard/attachments/20130116/71acf5d8/attachment.htm