[FM Discuss] Style Guide?

[William Abernathy]

Adam:

I first want to say that I'm happy to see that you're being honest with me here, 
and I want to emphasize that I do respect your disagreement.

Clearly, you have a viscerally negative sentiment towards a style guide, and I 
want to understand better what informs that sentiment. I have made a few 
arguments in favor of a guide, and I ask that you take some time to consider 
them and address them. Also, I want to know on what you base your strong 
opposition. It seems to me that your response is disproportionate to the 
proposal. I have never experienced a style guide as being anything but a 
positive thing, a means to set aside disagreements and improve the consistency 
and quality of work. You view it as a "policing" effort that discourages open 
collaboration, almost as if it were a means to bully people. This is honestly 
quite outside my experience. I cannot see how someone who is over the emotional 
hurdle of having their work edited by strangers to be resistant when the editor 
cites an authority uniformly agreed to by the group, rather than applying rules 
someone cooked up at the start of the project because (rightly or wrongly) they 
seemed like a good idea at the time.

It looks to me as if you've had a raw deal from someone brandishing a style 
guide. Can you tell us what you've experienced that makes this seem like such a 
bad idea to you? Would it change your opinion to have an agreed-to style guide 
with the group understanding that it is a guide, not an edict?

--William



adam hyde wrote:
> hi,
> 
> ok..I really do not want to see FM adopt a style guide as policy and I
> do not want style guide police. I absolutely disagree with your position
> on this and I will not support it.
> 
> If you wish to write a style guide and hope others adopt it, fine. But I
> will not make it the default for manuals. Style policing will deter
> contributions. At the end of the day we are about collaborative
> production of content and keeping the doors wide open, letting them do
> as they wish, we are not about forcing people to adopt _a_ way of doing
> things.
> 
> adam
> 
> 
> On Thu, 2009-12-03 at 11:37 -0800, William Abernathy wrote:
>> 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
>>
>> _______________________________________________
>> Discuss mailing list
>> Discuss at lists.flossmanuals.net
>> http://lists.flossmanuals.net/listinfo.cgi/discuss-flossmanuals.net
> 
>