[Bf-docboard] Proposal for restructuring the user manual

[brita]

replying with feedback on the proposal and on some things that I currently
think could be improved.

*tl;dr:*
- I would start by focusing on more introductory sections and hold on other
big restructurings for whenever is a good timing. Doing the 'Editors' would
be big.
- We need to speed up on having a platform for better communication and
task management
- I would not do an 'Advanced' section.
- I would not put any videos


I would maintain a 'Getting Started' as is now, and not replace it with the
current 'Basics' section (or did you @gaia mean only change the title?) ,
*'Introduction'* - keep
*'Installation'* - keep, but do a really big cleanup, put the
*'Troubleshooting'* here too, also trimmed

Then the mess starts, I don't really like videos as they are harder to keep
up to date, and to internationalize. I don't oppose either, if we define a
good infrastructure to support videos, and
 if they are not many.
I think that they should not replace text, so with or without video:

*'Preferences'* - right after installation. this can have both a 'setting
up blender for the first time', with 'do you have numpad? 3button mouse?..'
simple stuff, and a full reference even though users won't understand some
of the 3d space manipulation nuances. otherwise, this can go after basics.
The internationalization of the UI sould be mentioned as soon as possible
for users who are following translated manuals.

*'Interface' *explaining windows/editors, splitting, etc and how to get
around, then

*'Basics'* - with:
  - setting the default scene,
  - mentioning preferences (if not mentioned before)
  - help system
  - quick rendering. also say we have different render engines
  - quick whatever so that people can just get around before delving deeper
on anything
  - take screenshot and screencast away from this section

*'3D Interaction'* - this section currently looks quite complicated and not
very well encapsulated.

*'Data System'* - I would put this very early, not in advanced, so that
people understand quickly what are objects, and datablocks, users, fake
users and that data with no users gets deleted, how linking and appending
works. The philosophy of scenes and worlds, and the outliner. I really
think this is part of the basics, not advanced.


All the other sections and generic structure:

As for the *Editors* organization, I have mixed feelings about it. it is
ever a complex subject.
I do agree with having a reference per editor.
About the structure, some editor pages fit nicely inside other sections
(eg. outliner in data system, python console in scripting, 3d view in 3d
interaction..). Some are generic or fit in multiple sections, like
'properties'
So, have a list of editors, or the editors inside more or less subjectively
appropriate sections?
I would propose, mentioning the editors inside wherever it makes sense,
with workflow guided explanations, and have a section 'Editors' with all of
them to be used as reference.
This is quite a big restructure, though, and dangerous to have information
repeated, I would hold off on it for now.

The whole manual probably needs a review to support better the fact that
there are multiple render engines. I see that 'blender internal' 'cycles'
and 'freestyle' are not easy to spot in the current structure.
These were lvl1 chapters in the wiki, why was this changed?

*'World' *- the stars feature doesn't exist anymore.. so.. trim and include
this in rendering?
Modeling, Modifiers, Rigging, Constraints, Animation, Materials, Textures,
Rendering, Compositing

*'Glossary'* are we using that? do we intend to?


I would avoid calling 'advanced' to anything. It really depends on the
background of the user. for some rigging is advanced, for others it's
exactly what they want to read and having it on an 'advanced' section,
makes it look like that's not a normal use case for Blender. same for
'physics' or 'motion tracking' or anything really.
Putting 'Extending Blender' in advanced, will scare users from scripting.
'Data Systems', imho should be after 'basics', and 'Game Engine' is also
not advanced (more like unsupported, but it shouldn't be more advanced than
MT or video editing).


@gaia if going forward with the Editors, would you be available to do it?
If you are motivated to do it now, I say 'don't hold off and go for it!'
Even if you don't have the knowledge for all the editors, it would be good
to have something more. But not being easy to deal with structuring, data
duplication and massive reviewing of sections, I just meant that it is a
lot of trouble when there are a lot of other high priority things that are
easier to tackle first.

cheers!
Inês Almeida / brita_
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.blender.org/pipermail/bf-docboard/attachments/20141227/b5aefd19/attachment.htm