[FM Discuss] Style Guide?

[Lana Brindley]

Tomi Toivio wrote:
> Hi,
> 
> Big companies use style guides to make the documentation anonymous - the
> documentation created by big technology companies is impersonal and it is
> impossible to tell who wrote which section in what manual.
> 

<snip>

I'm not going to address the larger subject here (I have already done so 
in another email), but I do want to speak to this point.

Some of the difficulty in creating absolutely awesome technical 
documentation is in the ability to write about a dry, detail-heavy topic 
in language that will not bore your reader. The magic comes in when you 
try and captivate them - make them want to read more, to learn more. 
That doesn't mean encapsulating the content in big words, fancy 
language, or poetic style. It's about getting the information to the 
reader succinctly, accurately, and efficiently. Where a book is written 
or maintained by more than one author, the voice across the book should 
be consistent, simply to avoid disconcerting the reader. Indeed, the 
voice across a company should be consistent, also. This is in no way a 
bad thing, but in fact something to be strived for. As for 
'anonymization', if companies really wanted to that, they wouldn't list 
the authors' names in the document at all.

Of course, a collaborative group project like FLOSS manuals isn't a 
company, and shouldn't have the same desire for homogeny. But that 
doesn't mean we shouldn't have the same over-arching goal - awesome 
documentation. To achieve that, there needs to be a minimum acceptable 
standard. That way, when someone reads a manual developed by this group 
and loves it, they can come back and find another manual, on another 
topic, at a later date, and love it just as much.

There is nothing more disturbing to a reader than to have styles, voice, 
and language changing not only book to book, but chapter to chapter.

Cheers,
Lana


-------------- next part --------------
A non-text attachment was scrubbed...
Name: lbrindle.vcf
Type: text/x-vcard
Size: 976 bytes
Desc: not available
URL: <http://lists.flossmanuals.net/pipermail/discuss-flossmanuals.net/attachments/20091204/c43c12e0/attachment-0001.vcf>