[FM Discuss] Style Guide?

[Lana Brindley]

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>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: lbrindle.vcf
Type: text/x-vcard
Size: 976 bytes
Desc: not available
URL: <http://lists.flossmanuals.net/pipermail/discuss-flossmanuals.net/attachments/20091206/1e3c17eb/attachment.vcf>