[FM Discuss] Style Guide?

[Andy Oram]

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