[Bf-docboard] Manual Structure project update 2

[Matt Ebb]

Hi all,

You may remember me posting about a project I've been working on  
alongside the BSoD, to improve the information design and structure  
of the reference manual. You can probably find previous emails in the  
archives.

Anyway, I've *finally* just about finished the enormous task of  
updating the various manual pages in the manual to use the consistent  
reference information template (http://mediawiki.blender.org/ 
index.php/User:Broken/ReferenceBoxGuidelines) - there are a couple  
that haven't been converted yet, I'm waiting for the next stage of  
this project. Im already very happy with the results so far, things  
look a lot clearer and nicer.

The next bit remaining in the project in my proposal ( http:// 
mediawiki.blender.org/index.php/User:Broken/ 
SummerOfDocs2006Restructure ) is tweaking the higher level structure  
of the manual, and splitting off the tutorials into a revamped  
tutorial section. I decided to wait until I'd been through all the  
manual pages already to do this, since now after reading and editing  
just about every page, I have a very good understanding of the state  
of the manual, what is missing, and what should be tweaked.

I've given it some thought, referenced the old discussions and have  
written a proposed, comprehensive TOC here: http:// 
mediawiki.blender.org/index.php/User:Broken/ManualTOC . The idea is  
to have another tutorials TOC with top level containers that mirror  
those in the reference manual, both crosslinked (as you can see in my  
page). This keeps the reference manual clean and focused, but also  
allows nice cross-referencing. Notable differences between my TOC and  
the current one are:

* I've included yet-to-be-written placeholder titles based on  
information I found was missing from the manual. Some of them (such  
as node docs) are already elsewhere on the wiki and just need to be  
copied over & consistent-ified. I also think it's worthwhile to keep  
placeholders on the TOC page, since although it looks less  
'professional' (the manual is hardly at a professional level now  
anyway), it shows people what needs to be written, and encourages  
contribution there.

* I've tweaked some names, and removed all the "/PartIII/" etc.  
designators from the page titles, for a few reasons.
  a) They're unnecessary - who cares if it's part 5 or 6, the content  
is what counts
  b) It makes it harder to crosslink to other pages, instead of just  
intuitively writing [[Manual/Subsurf]] if I want to link to the  
subsurf page, I have to go and hunt down the section number too in  
order to make my link
  c) It makes the ordering of chapters inflexible, since it means all  
new chapters (such as one on compositing) have to be added at the end  
of the manual, to prevent changing all the links around. I'm happy to  
take care of moving current pages to the new titles, without '/ 
Part/' (with auto link redirection of course).
  (btw, the black text in parentheses is for description now, and  
won't stay).

So anyway, I thought I'd put this up for comments for a couple of  
days, and then go ahead and finish the job! Let me know what you think.

cheers

Matt


------------------------------------------
Matt Ebb • matt at mke3.net • http://mke3.net



-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://projects.blender.org/pipermail/bf-docboard/attachments/20060729/cb25da08/attachment.htm