[FM Discuss] Style Guide?

Thu Dec 3 14:17:29 PST 2009

Hi,

Big companies use style guides to make the documentation anonymous - the
documentation created by big technology companies is impersonal and it is
impossible to tell who wrote which section in what manual.

Use of such style guide might greatly limit the creativity and motivation of
an accidental contributor to FLOSS Manuals. First of all it would require
contributors to read a huge guide before they actually can write a word -
not very motivating. And not all people would even be interested in such
things while they would be perfectly able to write nice documentation for
FLOSS.

Also it would establish a uniform style that might actually be boring for
many people - everybody has their own writing style, why try to change it
into something uniform? I mean very different styles would work for
different types of manuals.

Regards
Tomi

2009/12/3 adam hyde <adam at flossmanuals.net>

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

-- 
Best Regards
Tomi Toivio
Open Source Coordinator
http://fi.flossmanuals.net/
tomi at flossmanuals.net
+358445488856
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.flossmanuals.net/pipermail/discuss-flossmanuals.net/attachments/20091204/7ec66f62/attachment.htm>