[Bf-docboard] Wiki upgrade 2011

[Michelangelo Manrique]

quite agree mindrones, i'm in if you need someone else on the team

Mich,
BFCT

On Sun, 2011-09-25 at 12:06 +0200, mindrones wrote:
> Hi,
> 
> at the moment we're all recovering a bit after all these months of work
> on the new wiki :)
> 
> Surely, after a bit of rest we'll concentrate more on the contents, just
> now exactly now :)
> 
> 
> RE: manual structure + pdf
> ------------------------------
> 
> Before we start discussing the structure or the pdf, I'd prefer we
> concentrate on the long awaited Blender Reference.
> 
> As explained at the Blender Conference 2010 Documentation Roundtable,
> 
> http://download.blender.org/documentation/bc2010/blender_documentation_roundtable.pdf
> 
> we would like to be able to separate the Reference from the Manual.
> 
> Most of the contents in the manual try to explain what a certain command
> does or which shortcut you have to press to use it, and that's not
> something you want to read in a manual.
> 
> Rather, the manual should refer to (or send you to) the reference when
> it comes to show a command, and concentrate on how to do things in
> general. It should not explain anything too specific (that's for a
> tutorial).
> 
> At the conference we did this example: say that you want to document
> texturing. Then:
> 
> - the Reference should explain:
>   - the various spaces/areas where you find the tools
>   - menus
>   - shortcuts
> 
> - the Manual should explain how to texture simple models (planes,
>   spheres) in order to tell you the basics of the texturing procedure,
>   highlighting problems and caveats in general
> 
> - Tutorials should explain how to texture specific models (say, a face,
>   or sintel's jacket, or a door).
> 
> Manual and Tutorials should not tell you press this and that or how to
> select a certain space in Blender, or how to split the window in order
> to work there. This is something that the reference should do.
> 
> At the moment reference and tutorial contents are quite well mixed in
> the manual, that is: you find shortcuts in the manual, and how to model
> a sword as well in the manual, and that's wrong.
> 
> --
> 
> As for shortcuts, rather than use
> 
> "press {{shortcut|w|1}} two times to subdivide the model",
> 
> we should use
> 
> "[[Doc:2.5/Reference/Modeling/Editmode/Subdivide|subdivide]] the model
> two times",
> 
> and let the user choose if to click on the link to "subdivide": only
> he/she knows if that information is useful or not to him.
> 
> I'd like that clicking or hovering on the "subdivide" link shows content
> in the TOC sidebar, if the content is not too big, rather than loading
> the subdivide reference page.
> 
> Also,
> 
> Doc:2.5/Reference/Modeling/Editmode/Subdivide
> 
> might be different from
> 
> Doc:2.6/Reference/Modeling/Editmode/Subdivide
> 
> so it's not much convenient to hardcode "{{shortcut|w|1}}" in the
> wikitext, because it's a nightmare to maintain.
> 
> --
> 
> I'd like to keep manual, tutorials and reference aligned, so that we
> have for example:
> 
> Doc:2.x/Reference/Modeling/*
> Doc:2.x/Manual/Modeling/*
> Doc:2.x/Tutorials/Modeling/*
> 
> hence I'd prefer to discuss the Reference structure first.
> 
> 
> The next step is to try to get an automated Reference from Blender's
> code, so when we get there, hopefully soon, IMHO we can discuss more
> about the rest. Otherwise we keep doing things manually, which is a
> massive task, and the wiki team is not large enough to cover well the
> whole manual/reference IMO :/
> 
> 
> I hope this clarifies things a bit :)
> 
> 
> 
> RE: wiki feature requests
> ------------------------------
> 
> Please file them at
> 
> http://projects.blender.org/projects/blend-doc/
> ("Feature Requests" tracker)
> 
> it's easier to keep track :)
> 
> 
> Regards,
> Luca
> 
> 
> _____________________________
> 
> http://www.mindrones.com
> _______________________________________________
> Bf-docboard mailing list
> Bf-docboard at blender.org
> http://lists.blender.org/mailman/listinfo/bf-docboard
>