[Bf-docboard] Re: Re: Restructuring the documentation
Glen Moyes
metsys at icubenetwork.com
Wed Dec 14 04:12:32 CET 2005
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
More information about the Bf-docboard
mailing list