[Bf-docboard] The manual and the wiki

[Abuelo S. B. Chdancer]

I read the entire wiki prior to downloading v2.72a. It did not prepare me
for using the software and these days I do not regard it as my first
resource when I need to know anything.

I don't know if it is practical to tackle all the problems I see with the
documentation, and I don't know if others share my opinion, but here are
some ideas which may or may not have merit.


The wiki contains entire sections of verbatim copies.
Many of the screenshots are pre- 2.5
It lacks organization.
It lacks consistency.
It is sometimes wrong.
Many commands are not listed or left blank.
It is often written in a way that only someone who already understands the
subject would understand it.
It often lists all the variable in a command without explaining what the
command does or why you would use it.

Tackling these deficiencies would be a major task.

That task starts with tools tips and error messages which are part of the
documentation of software. Many of these are redundant or misleading.
(Examples in v2.73a...
Box filter : Tooltip: "Applies the box filter"  . It could read "Fast but
inaccurate")

(Applying modifier to bone: Having selected a bone the error message says,
"Can only be applied to bones" when it could say, "Change to pose mode
before applying modifier")

(Unwrapping UV map: Eror message says "Model uses inconsistent scaling
factors" when it could give the instructions for setting scale to 1 to get
a better map)

A useful manual obviously needs to be accurate, but it also needs to be
organized. Here are some ideas:

Multiple hyperlinked lists of commands:
1) Alphabetical
2) By Mode in which they are available
3) By the kind of task they relate to.
4) By shortcut
Those lists just link to a page that contains the function set-out in a
standard way with a header that includes links back to all of those lists
plus a note of related topics for further reading.

Two interlinked sections one of which is that standardized page per
function setting out:
Name of function
Brief description of what it does (avoiding repeating the name of the
function)
Brief description of when to use it
Brief description of how to use it.
Then links to details of the above.

On each such page it is easy to click to contents lists and to 'related
commands' and 'further reading'
Plus a note of the version of Blender that the information is based on.

The other would be organised more by activities but cross-indexed to the
above.

There is a way of helping to teach basic navigation of the 3D view- by
making the default set-up include those instructions as text visible in the
3d window together with large numbers representing the number keypad.


One of the great challenges in manuals is finding persons who understand
the software, but who can write for someone who does not.

I hope that I have not offended anyone with this list of comments. I would
like to see better documentation for this powerful and at times delightful
software.



On 12 January 2015 at 09:41, brita <britalmeida at gmail.com> wrote:

> Hi,
> only Doc2.6/Manual got deprecated in favor of manual, all the other
> namespaces are kept as usual. For example the Extensions namespace, for
> addons, exists just the same:
> http://wiki.blender.org/index.php/Extensions:2.6/Py/Scripts
> Same goes for the Dev pages, the Ref and the new user's personal space
> pages.
>
> The new manual is really just supposed to replace the Manual, think of it
> as the new thing for the 2.7x series.
>
> Inês Almeida / brita_
>
> _______________________________________________
> 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/20150112/8adc15f8/attachment.htm