[Bf-docboard] Proposal for restructuring the user manual

[Campbell Barton]

On Sat, Jan 3, 2015 at 9:54 PM, Gaia <gaia.clary at machinimatrix.org> wrote:
> Here is a modified version for the navigation proposal with your
> proposed changes:
>
>      http://blog.machinimatrix.org/blender/manual/
>
> While doing this navigation update i realized that the Blender manual
> somehow "knows" that it is running within an iframe and it obviously
> hides the Manual navigation sidebar by default. So this was not my
> idea, it just "happened" :)
>
> Now... what about taking this as a chance to create multiple
> navigation trees for different purposes, like for example:
>
> - Riggers tree
> - Animators tree
> - Modellers tree
> - New Users tree
> - Maya Users tree
> - Reference tree (what we have right now)
>
> Then others (third parties) could even use this method to create their own
> special purpose manuals by reusing the blender "document nodes" and
> create their own document trees (and add their own document nodes
> as needed).
>
> Maybe the documentation writers would need to pocket the idea of
> writing "relational document nodes" instead of "hierarchical documents"
> (whatever that implies).


Talked with Gaia on IRC, not sure its useful to have multiple tree's,
while this isn't a lot of extra work (up-front), it means we need to
maintain & communicate multiple views on the docs (editors need to
update them)... we need a list of tree's somewhere... etc.

So unless we find its useful to have later on, I rather avoid the extra hassle.

> And as you can see the navigation tree on our blog is not even hosted by
> Blender.org but it just reuses the documentation "nodes".
>
> cheers
> Gaia
>
>
> On 03.01.2015 09:54, Campbell Barton 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