[Bf-docboard] The manual and the wiki

[Campbell Barton]

Hi Abuelo, thanks for the feedback, In general I agree with your key
points about the problems with the manual, we've discussed how to
resolve these problems already.

On Tue, Jan 13, 2015 at 3:26 AM, Abuelo S. B. Chdancer
<playadance at gmail.com> wrote:
> 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")

This is a bit of a difference, explaining the outcome vs what actually
happens (in this case 'Fast but inaccurate' is probably more helpful
though)

> (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)

Disagree here, first of all - its an info-message, not an error.
Telling the user to go and scale their object to 1, isnt correct
because the issue is non-uniform scale... or they could apply scale.
Or if it looks acceptable they could leave as is.

I think its not reasonable to instruct uses in these cases,
This is just a hint that the result might not be what the user is
after, and they can re-scale their object if they dont like the
outcome.

Scaling objects is a common operation, that users can do this themselves.

But I see where you're coming from and in some cases it probably makes sense.

> 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.

These would be nice, but not sure they're essential.

The manual now has an improved structure (for main sections) and its
searchable, so think this gets us a long way.

> 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.

We can discuss a lot of bigger tasks, but the challanging part is how
to do (even the basics) with with the small team we currently have.

How to build the community too, help get others involved.

> 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
>>
>
>
> _______________________________________________
> Bf-docboard mailing list
> Bf-docboard at blender.org
> http://lists.blender.org/mailman/listinfo/bf-docboard
>



-- 
- Campbell