[Bf-docboard] Manual Structure project update 2

[Will DeVore]

Hey Matt,

IMHO, I think you are doing a great service to the docs.

I like the idea of splitting off the tutorials and your proposed 
restructure looks good. The BoxGuidelines template looks easy to deal 
with. I also agree with the removal of the page title designators.

I look forward to picking back-up when your project and the other BSoDs 
are completed.

Have you thought about how to handle versions between Blender. Sometimes 
Blender changes quite drastically. What about having some sort of filter 
that kinda morphs the document according to the version of Blender you 
are interested. I think of it much like CSS for web pages. Perhaps there 
could be a list box or something at the top for choosing the version 
where certain sections may appear or disappear or may even change. We 
could use templates to control what docs go with which versions.

Just food for thought....

Off to Siggraph now. ;P

-Will

Matt Ebb wrote:
> 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
>
>
>
> ------------------------------------------------------------------------
>
> _______________________________________________
> Bf-docboard mailing list
> Bf-docboard at projects.blender.org
> http://projects.blender.org/mailman/listinfo/bf-docboard
>