[FM Discuss] Style Guide?

[Janet Swisher]

In my view there are two potential audiences for a style guide:
writers and editors. I understand Adam's point about not wanting a
style guide to be a hurdle in front of potential writers, at the same
time that I appreciate all of William's arguments for why it can be
helpful to editors. I don't think that these goals need to be in
conflict.

It sounds to me like Adam wishes to avoid setting policy while
encouraging emergent conventions. Culture rather than rules. However,
culture consists of rules that are not written down. Which makes it
difficult for newcomers to know how to fit in, even when they want to.

In fact, we have a de facto default style guide. Of the manuals on the
site that have a "Writing Conventions" topic, most have copied it from
the OLPC/Sugar manuals. Only a few of those have modified it to change
the list of maintainers (do Walter Bender and Adam Holt know they're
maintaining so many guides?) or the OLPC-specific usages, such as how
to refer to "the XO".

To me, that's evidence that some projects feel the need for a style
guide, but don't want to put much work into it. I think it would be
great if projects would use a more generic default, such as the
conventions for the Booksprints manual that Andy posted the link to.
But it should also be kept fairly minimal, to limit the cognitive
burden on writers who use it (if they even look at it). Projects that
copy it can adapt it, adding only what is relevant to their needs.
Editors who want a "definitive" reference can use that in the absence
of a specific style guide for the project they're editing.

--Janet

On Thu, Dec 3, 2009 at 1:55 PM, adam hyde <adam at flossmanuals.net> 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