[FM Discuss] Style Guide?

[adam hyde]

hey Andy,

Nice points. 

How about a middle ground - to discuss putting a chapter in the FM
manual on what style guides are and the pros and cons with an example
guide...this might be worth considering

I very much appreciate Martins point :
"perhaps there could be some sort of way of
adding comments to the different manuals about the style used in that
particular manual. In that way there could maybe be an exchange and a
learning process about style, rather than some sort of central committe
style Scripture that tells people how to write."

We are working towards this (comment features) with booki...

adam


On Fri, 2009-12-04 at 09:01 -0500, Andy Oram wrote:
> I'm amazed--although I shouldn't be in retrospect--how quickly this issue sliced down into fundamental philosophical and sociological questions. Which is a good first sentence to make panicky readers delete this email message, so I hope you don't.
> 
> Adam is sort of saying, "Let people do what comes naturally, and talk it out." This is pretty much one end of the spectrum. Nobody is at the other end of the spectrum (force everyone to read and adhere to a style guide) but some occupy various points along the way.
> 
> Maybe instead of having Writing Conventions for each manual, we should have a "clean-up" document that stands alone. If contributors notice inconsistencies that can be annoying or confusing, they can check that document and make fixes.
> 
> As others have said, it can be tiring to make people hash out differences when it doesn't really matter whether you're using British or US spelling--just pick one. If you can check a respected document, it makes life easier.
> 
> I personally think, after decades of forcing US usage on authors, that British should be used. Look at the world around us. How many countries use US spelling? Just the US.
> 
> Collaborators can also ignore or overrule the clean-up document. People from projects that have their own conventions can stick to them. Adam, I think your point that many projects have their own style guides is an argument for providing one for FLOSS Manuals, so long as it's optional.
> 
> It's worthwhile hashing out positions in advance and making recommendations. For example, I also think italic is superior to bold because it's more pleasant to look at (on the printed page, at least). Such recommendations can be helpful.
> 
> Inevitably, we'll have arguments over the style guide. But it's still easier to let people who care about such things work at the meta-level than to do it for each book.
> 
> Andy
> _______________________________________________
> 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