[Bf-docboard] Restructuring Proposal

[Ewout Fernhout]

Hello Glen,
I'm glad you took the proposal one step further. The discussion
currently in the wiki was started by me, but I have had too many other
things to do in the past few months to be able to do anything with it.

I like a lot of the ideas in your proposal, but I still have a few
questions/remarks:

You keep saying "core documentation, theory, tutorials, reference
material, and so on", but I can't really make out anything more than
the first three. Isn't the core documentation reference material? Can
you give an example of "and so on". The first thing that comes to my
mind is the thematic volumes, but these cannot really follow your
structure. I even doubt that it is neccessairy to put energy in these
before we have the basic documentation (core, theory, tuts) ready.

I've also changed my view a bit regarding the in-doc mini tutorials. I
DO think that things like "modelling a glass" don't belong in the core
doc's but on the other hand, mini examples should be there. Otherwise
documenting how things actually work is going to be very hard. This
doesn't have to be explained in-depth, but a time-series strip can be
very effective here (i.e. "This tool in action:" followed by some
images). These are on the boundary of documentation vs. tutorials, but
are VERY important, even for the advanced user! They will make the
sections much more recognisable.

As for final publication (print) we should decide whether to combine
these volumes or not. If you intend the manual to be that way (first
theory, then documentation, then tutorials), you should probably
present it like that too. Experts will have to do with either the
online version or they have to skip the "unnecessary" parts --
remember that the book-form is comfortable for those who read the
WHOLE thing (i.e. beginners), and online docs serve very well as a
look-up reference. Seperation = quality loss in my opinion.

A very important thing (which is actually a message to all docboard
members), is the structure of the text. Something that was probably
born from a technical gimmick (docbook) is the image linking. Image
linking/numbering should NOT be necessary in my opinion!
Images, just like text, are there to communicate something; they
containt information. Not only that, but they really belong to a
specific part of the text. If people have to skip to another part of
the page or even the next page "see image 12b", they are lost
completely in the reading.
Some of you might have read the books by Edward Tufte (if you haven't,
I can really recommend any of his three big ones!), and he too
promotes inline graphics - as opposed to graphics that fit some kind
of grid. If the images flow nicely with the text, the user will have a
much better experience with the documentation. In some cases, this
might lead to images being used twice, but I don't see a problem with
that at all. The second image can be smaller or show just a portion,
but it's really important to keep the reader reading without
interruption.

Another thing, which I want to talk about, is the presets that blender
comes with. I have seen a lot of people that suggest to newbies to
switch RMB/LMB & turn on auto perspective... Now I really think these
very simple adjusments should be considered seriously as the default
or, better even, make this an option in the windows installer "I'm an
existing user" or "I'm a new user"... Not sure still how to
communicate this. For cross platform compatibility this could be
replaced by a first-time-use screen within Blender.
As for tutorial compatibilty this raises some issues of course, but I
myself have been using these settings since the first time I used
blender, and NEVER had any problems interpreting tutorials. I don't
think about it (never did too), because obviously you don't "read"
that part of a tutorial that you already understand.
Still this is a difficult decision, since it involves many emotions of
existing users too. I'd like to have some feedback of this board
because we focus on the learning experience, and this could be an
important issue.

Ewout

On 12/30/05, Glen Moyes <metsys at icubenetwork.com> wrote:
> We've been discussing a possible restructuring of the documentation, so
> I wrote down a possible outline for it, in addition to my previous
> proposal on cross linking the different volumes in the documentation
> (theory, core, tutorials, reference, etc). You can view it on my User
> Talk page on the Wiki.
>
> http://mediawiki.blender.org/index.php/User_talk:Metsys/Reconstructing_the_Blender_Manual
>
> For those of you who are already familiar with my previous proposal from
> last month, just skip down to the "Proposed Outline" section. Otherwise
> read it all so you know where I'm going with it. I'd like to get some
> feedback on how we can better structure the documentation. I'm all ears,
> so just add to that talk page or email suggestions. There is also
> already some discussion on this topic here:
> http://mediawiki.blender.org/index.php/Meta/Restructuring_the_Manual
>
> - Glen
>
> _______________________________________________
> Bf-docboard mailing list
> Bf-docboard at projects.blender.org
> http://projects.blender.org/mailman/listinfo/bf-docboard
>