[FM Discuss] Style Guide?

[Anne Gentle]

Hi Lana -
I do hope you don't go - many of us volunteering for FLOSS Manuals believe
strongly in style guides. The OLPC / SugarLabs one is extremely useful, but
also quite simple. I put in many hours ensuring consistency of those books.
I personally value content creation over debate on formatting, though. But,
that does not and should not deter you and others from maintaining and
editing for style as you see fit.

What Adam's trying to convey is that we gather content from many sources.
For example, the Firefox book sprint used content from the excellent Mozilla
knowledge base. See http://support.mozilla.com/en-US/kb/Style+Guide. Many
open source projects take style quite seriously, so we could not and would
not try to convince them that FM has an overarching style that "must" be
used in order for the content to be part of the book sprint. It's simply not
going to get as much done in as short a time. Not that efficiency is more
important that quality, but we are working with many contributors and varied
content.

I hope that helps you understand a maintainer's viewpoint as well as someone
who believes in FM's aim of "free documentation for free software." Thanks
for your thoughts and for contributing your own perception and experiences.

Warmly, (though it's freezing here in Austin!)
Anne


 *Anne Gentle*
annegentle at justwriteclick.com
my blog <http://justwriteclick.com> | my
book<http://xmlpress.net/publications/conversation-community/>|
Twitter <http://twitter.com/annegentle>



On Sat, Dec 5, 2009 at 9:36 PM, Lana Brindley <lbrindle at redhat.com> wrote:

> Hi Adam,
>
> Comments inline below:
>
>
> adam hyde wrote:
>
>> hey,
>>
>> So back from German lessons, I have my coffee n couscous, and I wanted
>> to reply to some points made on the list directly before working on
>> Booki. So here goes...
>>
>>
>
> <snip>
>
>
>
>>
>> Lana :  "In my experience, writers like nothing more than to argue the
>> finer points of grammar and spelling, word use, and what - exactly -
>> constitutes word abuse."
>>
>> - hi Lana. Welcome aboard! You have stepped right into the fray! :) I am
>> very sorry but I really have to disagree with you strongly on many of
>> your points. I hope it wont chase you away!...
>> In my experience, having been around FM for longer than it has existed,
>> and also I have lead 16 or so Book Sprints - I have never experienced
>> this fighting of authors over word usage. I have found that it gets
>> settled pretty expediently and calmly. I'm my experience contributors (I
>> prefer the term since writers does not accurately profile how most
>> people contribute since usually all those involved are at some point a
>> writer, editor, formatter, critic, reader, illustrator etc) like most to
>> contribute and do it with minimum fuss.
>>
>>
> I'm sorry, perhaps I should clarify. By "argue" I probably more accurately
> mean "debate". The word "argue" does imply a certain level of angst and
> aggression that I didn't intend to convey.
>
> I also would like to draw your attention to my statement that this is "in
> my experience".
>
> The writers that I know and have known, have always enjoyed debating the
> finer points of language and grammar. I don't know if that culture exists in
> FM, as I've only just arrived. It could be that it just does not occur here
> as it has in other community writing I've participated in.
>
>
>
>> Lana : "I know of no professional writer or editor who would even
>> consider attempting to publish quality documentation without some kind
>> of style guideline"
>>
>> - There are three points I would like to make in response. (1) I know
>> many 'professional writers and editors' that do like to contribute to FM
>> and do so without reference to style guides. (2) FM is not a profession
>> (3) 'professional publishers' have written to me because they wish to
>> distribute FM manuals - seems to be good evidence on your terms that we
>> are doing ok
>>
>>
> Again, I was referring to writers and editors that I personally know, none
> of whom write (that I know of) for FM. To put it more clearly, I personally
> am hesitant to write without a style guide to back me up. Other writers and
> editors that I work with have often expressed the same sentiment. I have no
> doubt that many people who have contributed to FM do not feel the same way,
> however. I also think it is likely that people who *do* feel that way have
> contributed regardless, though.
>
>
>
>> Lana : "I believe that no documentation project should go ahead without
>> one, and so I think it's an appropriate place to begin."
>>
>> - We have 50 manuals. Many translated in an array of about 20 languages.
>> we have about 15000 PDFs downloaded each month, increasing hits to the
>> site, expanding contributor base of 'professionals' and
>> 'non-professionals' alike (I am sorry, I very much dislike the dichotomy
>> of 'professional'/'non-professional'). I know of only a few of these
>> contributors that take account of any style guide. The docs looks good
>> to me. We are getting plenty of people creating new projects without
>> style guides. I am sure these will also be excellent projects.
>>
>>
> As do I. I'm not saying that a manual written without a style guide backing
> it up will be a bad manual. I'm saying it will be inconsistent. Whether you
> think inconsistency is a bad thing or a good thing is for you to decide, not
> me.
>
>
>
>> Lana : "There is nothing more disturbing to a reader than to have
>> styles, voice, and language changing not only book to book, but chapter
>> to chapter."
>>
>> - I absolutely disagree. There is nothing more interesting than
>> diversity of approaches to quality content.
>>
>>
> Well, each to his own, I think.
>
> My own experience would indicate otherwise, but I'm not about to force that
> distinction on others.
>
> Quite frankly, it comes back to a simple disagreement on what we each
> consider a "good manual" I think.
>
> Considering my opinion differs so greatly from what appears to be the norm
> here, perhaps it would be best if I refrained from contributing at this
> point.
>
> Thanks for letting me know.
>
> Lana
>
>
> <snip tail>
>
> _______________________________________________
> Discuss mailing list
> Discuss at lists.flossmanuals.net
> http://lists.flossmanuals.net/listinfo.cgi/discuss-flossmanuals.net
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.flossmanuals.net/pipermail/discuss-flossmanuals.net/attachments/20091206/4eba9185/attachment.htm>