[FM Discuss] Style Guide?

[William Abernathy]

Hi all. I've been editing for the project for about a month. I am a technical 
editor by trade, and thanks to the current economic miracle, have plenty of time 
to donate to FLOSS Manuals.

As I've worked here, I've time and again been struck by the lack of any 
agreed-upon style guide. Questions of style are, as far as I can tell, addressed 
on an ad hoc, project-by-project basis. I believe this is a problem that we need 
to rectify, and would like to propose some solutions and hear your thoughts on 
the matter.

First, I'd like to argue the case for a site-wide style guide.

1) A site-wide style guide makes for a consistent product.

If I go to FLOSS Manuals and see a manual with strange internal conventions that 
make the work hard to understand, I will be less inclined to return for more 
documentation. If, on the other hand, each FLOSS manual has a consistent style, 
I will be more likely to recognize it as a valuable reference, and I will come 
back for more.

2) A site-wide style guide helps make a more efficient process.

I've suggested a site-wide guide to Adam. He suggested I should go to a 
particular documentation project, work on its guide, then see if I could float 
that to the larger group. This is exactly what I'm hoping to avoid. If I (or an 
author or maintainer) adopt a peculiar orthography to solve a problem I have on 
one project, this may or may not be applicable to all projects. Further, my 
"solution" may not be a good idea to begin with. If there is a debate about some 
question of style or usage, say on the Firefox group, once it's settled, it's 
settled there only. If it pops up again in OpenOffice, then the writers, 
editors, and maintainer have to hash it out in their group all over again, and 
may come to a different result.

3) A site-wide style guide makes life easier for editors.

As I look at FLOSS Manuals, I see a bunch of non-standard usage. I accept that: 
I'm an American, and my version of "standard" is different from the Commonwealth 
standards that prevail over much of the English-speaking world. When I have a 
tough edge case in my work, I appeal to an established guide -- usually the 
Chicago Manual of Style, but on occasion the AP manual, or Microsoft or Sun's 
style guides. When I write for a corporate client, they usually have their own 
in-house style guide. And on the Free/Libre/OSS tip, Wikipedia has its own style 
guide, which you can see at 
http://en.wikipedia.org/wiki/Wikipedia:Manual_of_Style. The problem I have right 
now is that I have no court of appeal. Should I refer to Chicago, or AP? Oxford, 
Cambridge, or Fowler? If I can't answer such a question, my choices are:
A) Don't touch a possible error.
B) Edit as I see fit.
C) Bug the maintainer for advice.
None of these makes sense -- If I leave the error, it stands, and quality 
suffers. If I edit, I may violate a local convention, breaking the work and 
increasing the maintainer's workload. If I bug the maintainer, then I am again 
increasing the maintainer's workload, for something he or she likely views as 
trivial, which leads me to point...

4) A site-wide style guide makes life easier for maintainers.

If a maintainer has to make a lot of localized judgments concerning matters of 
style, he or she is drawn away from the many other important jobs he or she must 
handle -- cultural, social, and technical. Further, the kind of questions that 
turn my crank as an editor will likely lie far outside the area of expertise of 
the average maintainer. I can't code my way out of a wet paper sack, and rather 
doubt I have the managerial and interpersonal skills needed to bring a FLOSS 
manual to completion. I respect the maintainer's formidable skill set. This 
said, I do know how to fix documentation, and the less I have to bug maintainers 
to get my job done, the happier both of us will be.

5) A site-wide style guide is better suited to ongoing maintenance.

If an end user wants to edit something, or an editor wants to join the party 
later in the development cycle, one FLOSS-wide set of rules will make it easier 
to join in. If you've kludged up a project-local style guide, odds are that a 
drive-by editor (one of my hobbies) is not going to see the book's local MoS 
before plunging in. You want to encourage people to contribute whenever 
possible, you need a single authority with "rules of the road" that writers, 
editors, and maintainers can appeal to A) while they work, and B) should 
disagreements arise over questions of style. Further, if I'm on my game, I will 
remember the FLOSS Manuals style point for the next project I touch, I won't 
have to look it up again, and we won't have to discuss it once, let alone twice.

I would like to suggest the following possible solutions to this problem.

1) We could adopt an external reference book, such as the Chicago Manual of 
Style, as a canonical reference. Were we to do this, we would likely end up with 
a much smaller online style guide to handle exceptions. I am uncertain as to 
whether this is an acceptable course for this organization, because A) Chicago 
(or any other MoS) is a proprietary text and as such does not conform to FLOSS 
principles, B) any one volume will not encompass the full scope of international 
English usage.

2) We could adopt the Wikipedia MoS as our style guide. This offers several 
advantages: the manual is universally accessible, free, and libre. While it is 
more rough-hewn than many of the published style guides, it's quite serviceable, 
and will not provide a bar to entry for any contributor.

3) We could generate our own home-grown manual of style. The advantage of this 
approach is that it would be 100% local to FLOSS Manuals and might prove 
valuable as proof-of-concept for the FM development style. The disadvantage is 
that it would be rather time-consuming, would involve a lot of discussion and 
compromise, and would likely take somewhat limited resources away from the 
projects at hand.

4) We could fork the Wikipedia MoS. I don't see the point in this, but you might.

In any of these solutions, I foresee that FM will as yet need a site-wide style 
guides to handle exceptions to either a book- or Wikipedia-based approach.

Thank you for considering this issue. I know that this will make my editing task 
easier, I believe it will make your product better, and strongly suspect it will 
attract more editing talent to FLOSS Manuals. If people want to SIG this, that 
might be a good way to address it.

--William