[FM Discuss] Style Guide?

[William Abernathy]

Tomi Toivio wrote:
> Yes,
> 
> I know that a style guide is highly useful when you are working as a 
> professional technical writer for a big company and it is hard to work 
> without one. However, FLOSS Manuals should be open for anybody to edit. 

This is a false dichotomy. Having a style guide excludes no one from editing. It 
is a guide, not a diktat.

> I think that the compulsory use of a huge style guide in every possible 
> manual would be a really big hurdle for a person who is not a 
> professional technical writer.

If you don't see the value of a style guide, you probably won't use it, and 
that's cool. I see the value of one, and if I had one, I would use it. The sort 
of questions I want answers to are, in all likelihood, questions you don't care 
about. For example, what rules govern the use of single, versus double quotation 
marks? Is the serial comma preferred? Do we frown on apposition?

It seems to me that in the admittedly small sample of seven people who've opined 
on this issue so far, we're divided into two camps: those who use style guides 
and consider them a valuable resource, and those who do not use them, and regard 
them as instruments of oppression.

> Why not just agree upon style guides separately for each manual? If the 
> writers are willing to use one they should do it.

As my initial post argued, a site-wide style guide offers consistency, 
efficiency, and resolution. Cooking up a style guide at the outset of each 
project is inefficient, leads to inconsistent product, and results in ambiguity 
and vagueness to editors. It also privileges founders and insiders over 
latecomers. Further, it assumes that all subsequent editors/contributors who 
were not present when the product's style guide was agreed to should read up on 
the conventions of each and every product they edit. Any wisdom gleaned from 
style discussions concerning a particular product remains sequestered within 
that product's discussions. Other groups/products cannot benefit from the 
deliberations of the first group, unless members carry that wisdom with them. 
This does not scale.

The closest analogy I can come up with would be to let cities and counties write 
their own codes regarding road signs. The information would be there, and the 
counties would let their local pride show in their clever use of fonts and 
colors, but drivers would not know if an octagonal red sign always means STOP, 
or whether it just might be a clever way of drawing attention to the harvest 
fair at the next intersection.

There is one other matter I want to address, specifically the odd notion that a 
style guide stands as a bar to entry for contributors. I have a Chicago Manual 
of Style, 14th Edition, on my reference bookshelf. It is over 900 pages long. I 
have used it for over a decade in my work. No one has ever demanded that I sit 
down and read it cover-to-cover before I touch their copy. I would be surprised 
if I've read so many as 100 pages total. Same goes for my dictionary. These are 
reference works. I crack them when I want to look something up, not when I want 
to be impressed by an author's quirky tone or clever turns of phrase.

I suspect the same is true of FLOSS Manuals, yet, by encouraging authors and 
editors to make ad hoc decisions concerning matters of style, we impose the 
requirement we profess to dread upon the reader: Before you can understand why 
this improper noun is capitalized, you must first go to the introduction and 
read the document conventions. I do not read manuals cover-to-cover, nor do I 
expect readers to do so. I pick them up, find the information I want, then get 
back to work. If I need to look up localized, book-wide documentation 
conventions before reading, I will look for a different work or simply be 
confused by, the clever orthography someone has invented to solve some perceived 
problem of comprehension.

> Also, here in Finland technical writers usually write in English when 
> working for companies and use the same style guides mentioned in the 
> original email. It would be hard to find such technical writing style 
> guides for the Finnish language. And at this stage we don't have the 
> committee needed to write one. 
> 
> Regards
> Tomi
> 

I cannot respond intelligently to the peculiarities of writing in Finnish. I can 
only state that by making our English writing a little duller, we will make life 
a lot easier on the poor sods who've agreed to localize our manuals to Swahili 
or Urdu. Since translation is one of the pillars of FLOSS, I would think, again, 
that a style guide would be a welcome addition and a present help in keeping 
things simple.

--William


> 2009/12/4 Lana Brindley <lbrindle at redhat.com <mailto:lbrindle at redhat.com>>
> 
> 
> 
>     This is an awesome idea. I'm a professional open source technical
>     writer. I've been lurking around on the FLOSS Manuals mailing list
>     for a little while now, waiting for a project to pop up that I can
>     get my teeth into.
> 
>     Firstly, your idea is a great one. In my experience, writers like
>     nothing more than to argue the finer points of grammar and spelling,
>     word use, and what - exactly - constitutes word abuse. Having a
>     style guide is the only way to successfully end an argument that
>     would otherwise go on forever. It also means that the results of
>     these discussions get set down and are used in future docs. No point
>     going back over the same arguments every second week.
> 
>     I am not going to try and convince detractors like Adam and Tomi
>     that a style guide is the way to go. Simply put, the concept of
>     producing documentation *without* a style guide is quite appalling
>     to me. I know of no professional writer or editor who would even
>     consider attempting to publish quality documentation without some
>     kind of style guideline (be it an internal word usage guide,
>     something like Chicago, or even just a preferred dictionary). I
>     personally would be hesitant to contribute to any project that not
>     only did not have a style guide, but actively prevented people from
>     creating one.
> 
>     All that said, as my very first FLOSS Manuals project, I would like
>     to offer to help William with the development of a FLOSS Manuals
>     Style Guide. I believe that no documentation project should go ahead
>     without one, and so I think it's an appropriate place to begin.
> 
>     Thanks William, for bringing this up.
> 
>     Cheers,
>     Lana
> 
> -- 
> Best Regards
> Tomi Toivio
> Open Source Coordinator
> http://fi.flossmanuals.net/
> tomi at flossmanuals.net <mailto:tomi at flossmanuals.net>
> +358445488856