[Bf-docboard] The whole enchilada

[Chris Burt]

>From the perspective of someone who wishes they had time to contribute
to the documentation of Blender I can say that this frustrates me as
well. I feel as though I'm competent to write documentation, I simply
do not have the time to do it. Its not a quick process. I thank the
people doing the work. The effort is noble. But I do find myself
coming across things like this that don't seem representative of the
quality of work you'd expect to find in an official Blender manual.
Again, no offense intended, but merely writing the documentation isn't
enough. There *are* some guidelines written on this matter, and if
they are ignored I'm afraid the effort is wasted and the work will
have to be done over again.

Regards,
--Chris

On 3/22/07, Alexander Ewering <blender at instinctive.de> wrote:
>
> Hi,
>
> not a regular on this list, but I just stumbled over a particular "User
> manual" page on Google and I just wanted to point out something which is -
> in my opinion - an issue.
>
> See the following page:
>
> http://wiki.blender.org/index.php/Manual/Render_Passes
>
> I was wondering if this is supposed to be the style of a rather technical
> manual, and if there is an overall binding "style guide" concerning
> writing style.
>
> Whoever wrote this manual page is a great comedian, and he probably also
> knows Blender pretty well, but I'm not sure if something like "The whole
> enchilada" "including the kitchen sink" is an appropriate description of the
> combined renderpass.
> Most non-native English speakers won't know Spanglish slang like "Enchilada"
> (I'm a lucky exception), and on the whole, 50% of the text on this page is
> comedy and not at all helpful in a technical way.
>
> I know this whole "A manual needs to be entertaining" speak. However, I
> suppose a style like this is better suited for a "Beginner's tutorial guide
> to Blender", and not for a reference manual, which this is - I suppose -
> meant to be.
> If I want to research an actual topic (this time, I actually wanted to
> research how to make materials not cast shadows and still be visible to
> raytraced lights), I don't want to read funny jokes about bosses - I would
> like to find the information I need, as quickly as possible, in order to
> continue my project.
>
> But well, this is just a random little pointer. I do not mean to insult the
> author at all. Really. But I don't think this is the right style for a
> technical manual.
>
> | alexander ewering              instinctive mediaworks
> | xx-mail.com/instinctive     http://www.instinctive.de
> _______________________________________________
> Bf-docboard mailing list
> Bf-docboard at projects.blender.org
> http://projects.blender.org/mailman/listinfo/bf-docboard
>