[Bsod-mentors] Doc structure project & summer of docs

[Matt Ebb]

Hi all,

I'm going to be doing a project alongside the summer of docs, with  
which you guys should probably be aware, and hopefully work co- 
operatively keeping it in mind. I submitted a proposal for the summer  
of docs, regarding the structure and information design of the user  
manual, and although it falls outside of the 'blender basics  
bootcamp' scope, the judges agreed that it was valuable and important  
enough to make a special exception for it, and run the project  
additionally. You can see the proposal here: http:// 
mediawiki.blender.org/index.php/User:Broken/SummerOfDocs2006Restructure

My project is partly concerned with some of the discussions that were  
on the bf-docboard mailing list late last year with the thread  
'restructuring the documentation'. The part of it that would  
influence the summer of docs most heavily is the idea of creating a  
stronger distinction between tutorial/theory and reference content. I  
go into more detail on this in the proposal, but basically, the  
mixture of tutorials and reference material in the Blender  
documentation is the source of many problems, and should be more  
cleanly separated (and cross-linked between).

Many of the BSOD proposals seem to be based on tutorials and theory,  
which is great. The wide range of topics will provide excellent  
prefaces/introduction chapters for each of the various sections in  
the reference manual. However, some of you may want to go into more  
detail in describing the various tools, which is great too, but it's  
important to keep detailed reference information in the user manual,  
structurally separate from tutorials on using them for practical  
purposes, and theory on "why" you'd want to use those tools.

For those of you writing up BSOD projects, I'd respectfully recommend  
and request a couple of things:

* If what you're writing contains both tutorial/theory and reference  
content, that's great, but try to keep them structurally separated in  
a way that when you're finished, the reference content can be  
integrated into the user manual, and tutorials can be put in a  
relevant place. This would probably mean writing your tutorials as if  
you're hyperlinking, then writing up a more detailed reference per  
tool separately. This will also help to keep your writing flowing, as  
people can follow the workflow and thought process without being  
interrupted by technical details.

Eg. "Give your empty a spherical force field and adjust the [size and  
falloff] to stop the softbody from sticking to the character"  ...   
[size and falloff] -> hyperlink to reference page with more detail on  
the effects that the various buttons have.

It may be tempting for you to just include everything in one big long  
document, for ease of writing, and to show what you've done. The  
work, however, will be much more valuable to readers at large if you  
can take some care to keep a good structure.

* If you're writing reference material, try to separate out common  
points of interest such as the tool's or option's name as it appears  
in the UI, the various ways to access it (hotkey/menu/panel/etc), the  
modes it's relevant to, examples, technical info, etc. This is to  
make it easier and less disruptive when I can finally go through and  
implement a consistent 'tool reference' template throughout the  
reference docs.

An example of the kind of information that would be included is in my  
proposal here: http://mediawiki.blender.org/index.php/Image:Broken- 
Templatemockup01_after.png but hopefully within the next few days I  
can come to a more concrete solution, and start investigating how to  
do the template syntax in mediawiki, even if it's not displayed all  
that nicely at the start :)

Anyway, that's all for now, I'll keep in touch about how things are  
going.

Cheers, thanks, and happy writing!

Matt