[Bf-docboard] The manual and the wiki

[Abuelo S. B. Chdancer]

Is there somewhere I can read up on what has been discussed or decided so I
can figure out what I can offer?

On 12 January 2015 at 20:25, Campbell Barton <ideasman42 at gmail.com> wrote:

> 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
> _______________________________________________
> 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/76e1ade1/attachment.htm