[Bf-docboard] Wiki upgrade 2011

[mindrones]

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