[Bf-docboard] Proposal for restructuring the user manual

Tue Jan 6 14:31:13 CET 2015

I've now moved the chapters to match the new structure (thanks to
Campbell's magical rst_remap script) and updated/added the index pages
where necessary.

Thanks for the feedback everyone, especially Gaia for initiating this :)

The next time you want to build, I recommend you first delete the 'html'
folder so it can build cleanly (otherwise the sidebar navigation and
previous/next buttons may get confused on a few pages, probably some
caching happening).

The `3d_interaction` chapter still remains, but that'll be split up and
moved to more appropriate places sometime soon.

I'll be adding tasks on phabricator in the next few days (will appear here
<https://developer.blender.org/maniphest/?statuses=open&allProjects=PHID-PROJ-c4nvvrxuczix2326vlti#R>),
but in the the meanwhile if anyone is looking for something to do, the
Editors chapter is pretty much blank :)

Cheers,
Greg

On 4 January 2015 at 01:12, Campbell Barton <ideasman42 at gmail.com> wrote:

> looks good! some comments inline.
>
> On Sat, Jan 3, 2015 at 10:28 PM, Greg Zaal <gregzzmail at gmail.com> wrote:
> > Ok, so at the moment this is how the structure looks (with some notes of
> > mine below it):
> >
> > - Getting Started
> >    - Introduction
> >    - Installation
> >    - Basics
> >       - Interface
> >       - Navigation
> >       - Help System
> > - Editors (reference for functions in each editor not covered in other
> > sections - e.g. layers, outliner usage...)
> > - Data System (data blocks, scenes, link/append...)
> > - Modeling
> >    - Sculpting
> > - Physics (particles, smoke, forces...)
> > - Modifiers
> > - Rigging
> >    - Constraints
> > - Animation
> > - Rendering
> >    - Blender Render
> >       - Materials
> >       - Textures
> >       - Lighting
> >       - World
> >    - Cycles
> >       - Materials
> >       - Lighting
> >       - World
> > - Compositing
> > - Motion Tracking
> > - Video Editing
> > - Grease Pencil
> > - Game Engine
> > - Extending Blender
> > - User Preferences
> > - Troubleshooting
> > - Glossary
> >
> > (raw - in case you want to edit it)
> >
> > Notes:
> >
> > No need to classify things as '2D' - each of those topics could be
> > considered 3D by at least some stretch of your imagination anyway (depth
> > channels, deep compositing...)
> > The "Getting Started" section should be as simple and brief as possible.
> > Troubleshooting is it's own thing that shouldn't be needed to start using
> > Blender. Same for: Render Engines, User Preferences, Data System, Game
> > Engine, Extending Blender - all important info, but you don't *have* to
> know
> > any of that to start using Blender.
>
> Troubleshooting is useful for developers to add to, we often get bug
> reports highlighting common misunderstandings & then dont really have
> a good place to collect problem->solutions.
>
> This would be handy to link users to from the bug tracker, and link
> from within the docs (like having a glossary of common problems).
>
> > As mentioned in my previous mail, Materials/Lighting/Textures/World have
> > been moved under Rendering, since those all change based on which engine
> is
> > used.
> > Constraints are under Rigging - I think of constraints as a tool for
> > rigging, but this is just my opinion.
>
> Its an approximation, but reasonable IMHO. for example you may *rig* a
> camera, so constraints are generally useful for rigging on an object
> level. even when armatures arent being used.
>
> > Should Import/Export be its own topic? Or under Data System or Extending
> > Blender?
>
> Addons have their own wiki pages, eg:
> -
> http://wiki.blender.org/index.php/Extensions:2.6/Py/Scripts/Import-Export/Autodesk_FBX
> -
> http://wiki.blender.org/index.php/Extensions:2.6/Py/Scripts/Import-Export/Wavefront_OBJ
>
> We *could* have an import/export section, but it can be more general
> information, and link to the pages for each addon to avoid documenting
> a lot of details, no rush for this though, we have enough work getting
> the existing manual in shape.
>
> > Cheers,
> > Greg
>
> >
> >
> > On 3 January 2015 at 10:54, Campbell Barton <ideasman42 at gmail.com>
> wrote:
> >>
> >> On Sat, Jan 3, 2015 at 12:50 AM, Greg Zaal <gregzzmail at gmail.com>
> wrote:
> >> > We have two currently supported renderers (game engine is it's own
> thing
> >> > imo, and not technically a renderer in the same context):
> >> >
> >> > Cycles
> >> > Blender Render
> >> >
> >> > Freestyle is not a renderer, rather a post-effect as I understand it
> (it
> >> > works on top of either BI or Cycles renders).
> >> >
> >> > Currently we have `Materials`, `Textures`, `Lighting` and `World` as
> >> > their
> >> > own sections - which made sense when BI was the only supported
> renderer.
> >> > However now that Cycles is around, It'd make more sense to me to move
> >> > the
> >> > materials, textures, lighting and world sections into the folder for
> >> > each
> >> > renderer. So the structure would be:
> >> >
> >> > Rendering
> >> >
> >> > Blender Render
> >> >
> >> > Materials
> >> > Textures
> >> > Lighting
> >> > World
> >> >
> >> > Cycles
> >> >
> >> > Materials
> >> > Lighting
> >> > World
> >> > [no need for a textures folder for Cycles]
> >> >
> >> > One problem with that is that textures can be used for brushes and
> >> > particles
> >> > too - should we then add `Textures` folders under those categories as
> >> > well?
> >> > Or instead keep it as it is currently with `Textures` in the root, and
> >> > cover
> >> > all the applications (BI/Brushes/Particles...) there?
> >> >
> >> > Alternatively, since Cycles is technically an external renderer,
> should
> >> > we
> >> > remove all Cycles docs from this manual, and instead have them
> >> > documented
> >> > elsewhere separately?
> >> >
> >> > Cheers,
> >> > Greg
> >>
> >> This is an awkward case, especially since Blender-Internal isnt having
> >> much development and we may make Cycles default soon.
> >>
> >> Suggest have 'Render -> Blender Internal', 'Render -> Cycles'
> >> sections, as suggested.
> >>
> >> Brush docs can just link to `Render -> Blender Internal -> Textures`
> >> _______________________________________________
> >> Bf-docboard mailing list
> >> Bf-docboard at blender.org
> >> http://lists.blender.org/mailman/listinfo/bf-docboard
> >
> >
> >
> > _______________________________________________
> > 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/20150106/adde0319/attachment.htm 