[Bf-docboard] Re: Re: Restructuring the documentation

[Glen Moyes]

Jean Montambeault wrote:

>
>Finding out what the hierarchy is among the Ways To Blender will proove to
>be quite an exercise. What would be the criteria and from whose point of vue
>? That could be very counter-productive. I'd think that the more objective
>criteria of 'Core' vs 'Tutorials' to be more efficient.
>  
>
Fortunately there isn't that many different ways to do things in 
Blender. Moving objects is one big exception, and I think the shortcuts 
is the one that should be taught first because the other two are weird 
even by Blender's standards. As a rule of thumb, it should be which ever 
is the most effective, like the new rigging process. However, some times 
you need to understand how to do it using method A before you learn 
method B, even though method B is more effective. In either case, it 
should just be the gut feeling of whoever is writing that part of the 
document. The order only matters in that it should make it easier for 
the user to understand the information.

And in reality, there are not that many instances were we have to worry 
about different ways of doing something in Blender. If that ever becomes 
an issue, it should just be up to the author to decide what should be 
taught first. They should have that intuition of what should be taught 
first that will make the most sense.

>
>>. The core documentation shouldn't contain ONLY the stuff
>>people actually use. The core documentation should briefly document
>>EVERY nook and cranny of Blender, and in an order that makes sense and
>>is easy to search for everyone.
>>    
>>
>
>Doing just that is going to be quite an achievement. If we succeed though
>there are chances for the documentation to reach a more stable state.
>  
>
Yeah, and that's what everyone is trying to do now, simply document 
everything. We have a lot of catching up to do, but now that it's on a 
Wiki, once we catch up it shouldn't be that hard to maintain. Yes, it'll 
be quite an achievement considering our past :).

>One point though : the entry point of all
>that incredibly vast documentation has to be a tutorial, one that'll explain
>how to best use the documentation. ;)
>  
>
Good point. We could have an intro to the documentation that explains 
how it's organized, but I think most people should get it right away, 
since there will be a big link at the start of each page that links to a 
big fluffy article on theory, and some links at the bottom for 
tutorials. I think that consistency will give them a big enough clue.

As far as execution, I have this entire Winter semester off which starts 
in a few days (I have classes during the Summer and Fall). Along with 
doing the Workshop full-time, I'll be writing a book to help instructors 
teach Blender, and I'll be putting a lot of that directly in the 
documentation. And I'll have some spare time to set it up those 
different sections. It's really not that hard, someone just has to do it. :)

Don't forget that this proposal isn't going to take much more work that 
what we are already doing now. It's mainly just organization, and a way 
to unify all the different methods of learning, which I've already 
figured out, and is quite simple. Aside from the theory section, it 
won't have that much more text than what we have already. So, I wouldn't 
really call it "vast documentation". That's the beauty of this solution. 
If I were to do everything that I've talked about in the Wiki right now, 
all I'd have to do is make "Manual/PartII/Basic_Mesh_Modeling" contain 
links to "Theory/Basic_Mesh_Modeling", "Tutorials#Basic_Mesh_Modeling", 
and "Video_Tutorials#Basic_Mesh_Modeling". Those pages can be updated 
independently from the core documentation. It's just cross linking. I've 
been wanting to unify all the learning resources from reference sheets 
to video tutorials in the documentation and this is how easy this is. 
Which of course means that I want to move the Video Tutorial collection 
on Blender.org (which I maintain, by the way), and permanently move it 
to the Wiki. The same should be done to the tutorial collection as well. 
All those sections have the same goal in mind, so why not put them in 
the same place.

I can start taking action on this project next week. I'd like to get 
some feedback from people on reorganizing the documentation. I won't 
like to have to redo all my work if we are going to reorganize it in two 
weeks.

- Glen