[Bf-docboard] Proposal for restructuring the user manual

[Greg Zaal]

Hey guys,

Overall, I like the proposal and agree with most of the comments so far,
with a few little notes:

About videos: I agree that they're generally a problem to maintain and
internationalize, though a video with no voice which simply shows the
results of something (e.g. ocean modifier includes:
http://vimeo.com/18911131 ) is perfectly fine imo.

A section on editors is a good idea, as long as we're not duplicating
anything too much. I see it as a place to describe the editors themselves,
and link to the other relevant sections when mentioning a feature.

Now about restructuring the whole manual:

When will "good timing" come? I'd prefer if we get all big restructuring
done fairly soon (before February perhaps). It doesn't have to be a
gargantuan task undertaken by only a handful of people - it may be easier
to start from the ground up and get module owners and volunteers to work on
a section each.

These people would become the "section owners" mentioned in
http://blender.org/documentation/contribute. We could rename the /manual
folder to /manual_old, and then they could scrub through the old manual for
their relevant content and move them to a new /manual folder. This way,
it'll be easy to tell what's still left to move (stuff still in
/manual_old), and keep note of where things were moved to so that it'll be
easier to fix all the broken links caused by the move.

Cheers,
Greg

On 28 December 2014 at 01:36, Campbell Barton <ideasman42 at gmail.com> wrote:

> 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
> _______________________________________________
> Bf-docboard mailing list
> Bf-docboard at blender.org
> http://lists.blender.org/mailman/listinfo/bf-docboard
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.blender.org/pipermail/bf-docboard/attachments/20141228/955e189a/attachment.htm