[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Style Guide (was Re: I'm a sucker)
I've unilaterally relabeled "I'm a Sucker" to Style Guide. It seems to
fit in more with how some of the conversation is going. I've written a
number of documents and documentation in my time. I guess one could say
I have a slightly verbose (especially in the first draft), royal "we"
style of writing. It fits in with my personality.
Firstly, is there a "Style Guide HOWTO" or could this become a section
of the "LDP Authoring Guide"?
If there is not, and even if there is, I'm not sure that it would need
to say too much. Nonetheless I think it should contain admonitions that:
* one should avoid gender-specific language wherever possible
- just to turn this one around a bit, why are crackers always
referenced as "he"?
* one should take into account that the audience is international, and
that the document could be translated by someone not the author
- covers things like don't show national prejudice
- don't assume cultural backgrounds
- try to avoid hard to translate idioms
* one shouldn't assume that all documentation is boring
- without being overtly critical of any vendor, boring documentation is
not read; despite what the management says, documentation that is
interesting, sometime humurous and maybe even readable is of much more
use than useless, wonderful, stilted management-liked documentation
In the end the documentation is for the end user. It is not for the
management of any vendor or specific user. Personally, I think the users
should have a say; if there really were such a dislike of "so-called"
non-professional documentation then those who don't like the current
HOWTOs can go and sanitise them.
I, for one, will still stay with the current HOWTOs. I cope with enough
boring drudgery in my life without having to read boring documents...
These are my opinions only :-)
And so it was that later
As the miller told his tale
That a face that at first was ghostly
Turned a whiter shade of pale....
To UNSUBSCRIBE, email to email@example.com
with a subject of "unsubscribe". Trouble? Contact firstname.lastname@example.org