[Bf-docboard] Proposal for restructuring the user manual

[Campbell Barton]

Thanks for the feedback.

Some of these more detailed points seem reasonable but I dont have a
strong opinion on them - so skipping those. Commented on others
though.

On Sun, Dec 28, 2014 at 10:04 AM, brita <britalmeida at gmail.com> wrote:
> 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.

Agree restructing a single section can be a good start, at some point
we might want to restructure all (Having a plan for final structure is
good, even if we don't do all at once).

> - We need to speed up on having a platform for better communication and task
> management

Isnt this phabricator?

> - I would not do an 'Advanced' section.

No strong opinion.

> - I would not put any videos

Agree, I rather not do videos, too much risk we make it once and it
never gets updated.

Later on if we have good docs, some short intro video the author can
re-record (when Blender changes), may be OK. but right now it feels
like taking on more work then we have time for.

> 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:

Agree, as I said above, some very short video link might be OK, but
further, I wouldn't want to rely on video as a content source for the
manual.

> '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?

This is new, a feature of sphinx/rst. It means we can reference
anything from the glossary. eg:

Text about :term:`Manifold Mesh` etc.

I think its good to keep, we've already de-duplicated a bit of content
by using it.

> 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).

Agree, if we do have an advanced section, it should be for _really_
advanced stuff, though if its kept small and documents exceptional
use-cases or internal details... it could be OK.

We could just not add for now, and only add if it makes sense, later
on (setting up cluster of physics sim baking PC's maybe *advanced*,
but also outside the scope of the manual).

>
> @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_
>
>
> _______________________________________________
> Bf-docboard mailing list
> Bf-docboard at blender.org
> http://lists.blender.org/mailman/listinfo/bf-docboard
>



-- 
- Campbell