[Bf-docboard] The manual and the wiki

[Raindrops From Sky]

Excellent question! I was about to post it myself.

I have already volunteered, and waiting for the "Go!" signal (with specific
instructions).

So, looking for the present status update, I went through the following
pages, expecting a quick link there:

   - http://blender.org
   - http://www.blender.org/get-involved/
   - http://www.blender.org/documentation/contribute

But they do not provide any clue.

While the planning is going on, a dedicated page should show the latest
conclusions.
This will prompt more inputs as we go.
Finally, when the planning stage is over, please put out what the
contributors have to do.

Thanks in advance!

Regards,
Narayan



On Tue, Jan 13, 2015 at 2:02 AM, Abuelo S. B. Chdancer <playadance at gmail.com
> wrote:

> 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
>>
>
>
> _______________________________________________
> 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/20150113/5ec1ee4d/attachment.htm