Style Guide (was Re: I'm a sucker)

[David Lloyd <lloy0076@rebel.net.au>]

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...

DL

[1]
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 ldp-discuss-request@lists.debian.org
with a subject of "unsubscribe". Trouble? Contact listmaster@lists.debian.org