[Bf-docboard] The whole enchilada
regenbrecht at gmx.net
Fri Mar 23 13:43:28 CET 2007
Alexander Ewering wrote:
> 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:
> 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.
This is a difficult question. If you enforce a certain style in the
documentation you will drive authors away. Since writing documentation is
quite hard work (and extremly bad paid in this case), an author may be asked
politely to obey the style guide.
The mentioned article doesn't fit in the manual, but the used "slang" is no
more difficult to understand than the rest of the page.
So in my opinion it boils down to the question: Should the style guide be
enforced - with the result of lesser articles being written?
I don't think so. As long as the information is correct, and the text is well
enough to read, the article should be kept - or reworked by someone who
thinks he has the time and knowledge to do better. But the authors are asked
to obey the style guide, and if someone really doesn't like it (like me), he
can write somewhere else.
More information about the Bf-docboard