[Bf-docboard] Re: Bf-docboard Digest, Vol 32, Issue 5

Sat Mar 24 00:16:50 CET 2007

I will try a rewrite on it for proper formal English usage

Most of the documentation should follow the same sort of language guidelines
as examples such as Wikipedia, so I believe idioms should (for the most
part) not be used

rpgsimmaster

On 3/23/07, bf-docboard-request at projects.blender.org <
bf-docboard-request at projects.blender.org> wrote:
>
> Send Bf-docboard mailing list submissions to
>         bf-docboard at projects.blender.org
>
> To subscribe or unsubscribe via the World Wide Web, visit
>         http://projects.blender.org/mailman/listinfo/bf-docboard
> or, via email, send a message with subject or body 'help' to
>         bf-docboard-request at projects.blender.org
>
> You can reach the person managing the list at
>         bf-docboard-owner at projects.blender.org
>
> When replying, please edit your Subject line so it is more specific
> than "Re: Contents of Bf-docboard digest..."
>
>
> Today's Topics:
>
>    1. The whole enchilada (Alexander Ewering)
>    2. Re: The whole enchilada (Chris Burt)
>    3. Re: The whole enchilada (Tom M)
>
>
> ----------------------------------------------------------------------
>
> Message: 1
> Date: Thu, 22 Mar 2007 19:21:45 +0100 (CET)
> From: Alexander Ewering <blender at instinctive.de>
> Subject: [Bf-docboard] The whole enchilada
> To: bf-docboard at projects.blender.org
> Message-ID: <Pine.LNX.4.61.0703221916180.2244 at time.instinctive.de>
> Content-Type: TEXT/PLAIN; charset=US-ASCII; format=flowed
>
>
> 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
>
>
> ------------------------------
>
> Message: 2
> Date: Thu, 22 Mar 2007 16:29:59 -0400
> From: "Chris Burt" <desoto at exenex.com>
> Subject: Re: [Bf-docboard] The whole enchilada
> To: "Blender Documentation Project" <bf-docboard at projects.blender.org>
> Message-ID:
>         <174615040703221329u6a27b396v6da423cc15d0c5b2 at mail.gmail.com>
> Content-Type: text/plain; charset=ISO-8859-1; format=flowed
>
> >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
> >
>
>
> ------------------------------
>
> Message: 3
> Date: Thu, 22 Mar 2007 12:42:50 -0800
> From: "Tom M" <letterrip at gmail.com>
> Subject: Re: [Bf-docboard] The whole enchilada
> To: "Blender Documentation Project" <bf-docboard at projects.blender.org>
> Message-ID:
>         <584fe5640703221342k3a8d95aek645443dad2fc6f00 at mail.gmail.com>
> Content-Type: text/plain; charset=ISO-8859-1; format=flowed
>
> > 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.
>
> I'm not sure if there is a style guide which states anything about the
> appropriate usage of idioms.  Those are both common US idioms.  Most
> open source documentation discourages their usage since they can cause
> confusion for non native speakers and for translators.
>
> In general they should not be used.
>
> LetterRip
>
>
> ------------------------------
>
> _______________________________________________
> Bf-docboard mailing list
> Bf-docboard at projects.blender.org
> http://projects.blender.org/mailman/listinfo/bf-docboard
>
>
> End of Bf-docboard Digest, Vol 32, Issue 5
> ******************************************
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://projects.blender.org/pipermail/bf-docboard/attachments/20070324/5acbb2b7/attachment.htm