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

[David Merrill <dcmerrill@mindspring.com>]

David Lloyd wrote:
> 
> 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

These are all good ideas. When I do an update to the LAG, I'll implement
your suggestions. This could be some time, as I am very busy putting
together other things.

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

I find the conversational style of many HOWTOs to be an essential part
of their charm. While one can find examples that are perhaps, ahem, a
bit *too* conversational, most are great. A balance between dry+boring
vs. conversational+wacky works well.

Regards,

-- 
David C. Merrill, Ph.D.
Linux Documentation Project
Collection Editor & Coordinator


--  
To UNSUBSCRIBE, email to ldp-discuss-request@lists.debian.org
with a subject of "unsubscribe". Trouble? Contact listmaster@lists.debian.org