[FM Discuss] Style Guide?

Sat Dec 5 03:13:15 PST 2009

On Thu, Dec 3, 2009 at 11:55, 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.

Adam was very clear on the first project I joined. Every body was free
to use US or UK spelling in English, and similarly for most other
issues. However, we do have people doing copy editing on every
project, and it is possible to create some consistency across chapters
in a given manual. I don't care much about the details of spelling and
style, except where they can cause confusion of meaning. For my own
writing, I insist on punctuation outside quotes, except when they are
part of the text quoted.

I like the idea of using consistent terminology within a document,
together with writing a glossary for almost all manuals. There will
necessarily be some inconsistencies between manuals, because we have
to respect established usage in different contexts. For example, IP
has  completely different meanings in a licensing and a technical
communications context.

> 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.

Don't try to make engineers, coders, and other Subject Matter Experts
(SMEs) follow a style guide. It inhibits them, and complicates
everything, and you still have to get the editors to go in and fix the
style. As a professional tech writer, I have always asked SMEs to give
me _unformatted_ text documentation, so I don't have to undo their
spacing and other manual effects before I apply paragraph and text
styles, tables, and numbering.

> 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.

It works surprisingly well.

> 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
>
>
> --
> Adam Hyde
> Founder FLOSS Manuals
> German mobile : + 49 177 4935122
> Email : adam at flossmanuals.net
> irc: irc.freenode.net #flossmanuals
>
> "Free manuals for free software"
> http://www.flossmanuals.net/about
>
> _______________________________________________
> Discuss mailing list
> Discuss at lists.flossmanuals.net
> http://lists.flossmanuals.net/listinfo.cgi/discuss-flossmanuals.net
>

-- 
Edward Mokurai (默雷/धर्ममेघशब्दगर्ज/دھرممیگھشبدگر ج) Cherlin
Silent Thunder is my name, and Children are my nation.
The Cosmos is my dwelling place, the Truth my destination.
http://www.earthtreasury.org/