[FM Discuss] Style Guide?

[adam hyde]

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...
 
William :" I cannot see how someone who is over the emotional  hurdle of
having their work edited by strangers to be resistant when the editor
cites an authority uniformly agreed to by the group, rather than
applying rules someone cooked up at the start of the project because
(rightly or wrongly) they seemed like a good idea at the time."

- this tone is one of the things that concerns me greatly. FM is a
community of projects. We do not profess to decide anything for
projects. If the 'we' you suggest stated that 'this is the style guide'
we use, then I can see proof readers coming back to the project and
editing content according to the style guide and other involved in the
content creation did not buy in to 'the style guide' at all. This is
infact how I have observed edits made to the Ardour manual by you
William. You suggested that you were angry that the content creators had
decided to use bold and capitalise glossary words. I don't see that you
have a right to get angry. What you have a right to do is to write to
the people involved and try and convince them that there are other ways
to do it, not to advocate for a style guide so that you can have your
position arbitrated by rules.

When it comes down to it I think a far better approach is to read the
content and determine the internal rules inherent in the text. Find the
internal consistencies and proof/edit according to that. If you think
there is something really hazardous, write to those involved and suggest
you edit a certain way and see what they say.


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.


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


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.


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.


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

- The writing conventions topic you refer to is copied by default since
i implemented it some time ago. I think its a mistake to say this is
evidence that people want a style guide. I think its more accurate to
say that the fact that no one has edited the parts you mentioned is
because no one looks at the guide. This to me is evidence we don't need
one. I should probably remove the link, perhaps this discussion is a
good catalyst to do so. Additionally, I have facilitated 16 Book Sprints
or so. I know of only one other person in FM that has led a Book Sprint
by themselves without my onsite assistance (I refer to Derek Holzer and
the Ardour manual which I helped with remotely). So I feel I'm in a good
position to talk to how Book Sprints work - I have only ever once or
maybe twice referred to the style guide in a sprint. I see the style
guide in this instance more as a pacifier than a textual tool since
showing the squeaky wheel that there is a guide seems to calm them down
even if no one uses it. In Sprints there is a specific methodology I use
to help manage consistency and quality. Its too much to go into here but
it involves the team agreeing internally what makes sense to them on the
fly (I discuss it in the Book Sprint manual to some degree) - it seems
to work well. Please check the quality of the Book Sprinted manuals and
tell me if you disagree.

William :  Do we frown on apposition?
- 'we' don't frown upon any content contribution. This kind of point
makes me very nervous about your intentions for a style guide.

adam



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