Future i Information : Style guide

Language

Use decent English. Since we're publishing almost immediately - mistakes are more likely to reach the page. Read new content that others write and mail the authors who have slipped up. It will happen, so let's fix it whenever we spot it.

Bill Bryson's Troublesome Words is a good book about many of the quirks in the English language. Since we're a British firm we should - in general - conform to standard British spellings. Where there is more than one way to approach something, we should just pick a convention and stick to it. Document it here for now. Ash is writing the dynamic style guide to allow for discussion over points of interest.

Markup

Use accessible, valid and relatively noddy HTML. Make everything look pretty in the site or section-wide style sheet. This also means:

Use the proper headings: Starting at H1 and cascading down to the lowest level you need. If they aren't the size you'd like to see, suggest what you would like it in a cascading style sheet (CSS).
Logical over physical: Using the logical styles - <em>, <strong> and friends - gives a more meaningful document. Only use the physical ones where it is the physical suggestion you really intend. Add classes to provide more flexibility. Avoid presuming in language how a browser will render something. Better to say 'highlighted like this' and wrap the same tags around the example than to try and spell out what a variety of renderers will do - and make damn sure they highlight it in some manner everywhere.
Accessibility: Avoid putting essential information only in the stylesheet - this harms accessibility.; Don't denote things solely by a graphic or colour either.; When describing how something is highlighted, don't describe the effect you expect in physical terms - since they likely will be different in different places. Instead use the same markup around a word like highlighted, or whatever works best in context.; Never say 'click here', unless you are railing against the dodgy use of the phrase. Not everyone has a clicking-device, and it adds nothing but noise to the text. Just make it a link around text that describes what is on the other end. Since you haven't screwed around with their link colours or turned link underlining off, they'll recognise it as a link and be on their way.

A-Z

To be dynamically generated, with comments et al. For now budvar-folk should add new cases here (in alphabetical order):

Dashes: If this were print, or if there was a good way to do it on the Web, I'd say use em-dashes surrounded by spaces for subclauses and em-dashes with no space for number ranges. As it is we can't. Don't use dash-dash to replace a longer dash, it just looks nasty. Use a single dash, and if you really must, monkey it in CSS. Better to use single dashes for now, and if browser support or the standards ever give us a good way to do them we'll use that.
Professional: Most spelling errors look sloppy. Spelling 'professional' incorrectly is much more careless than we want to look.
Web: When talking about web-gubbins running on the internet (the World-Wide Web), it's 'Web', when talking about the technologies involved, but perhaps deployed on some internal network then it is 'web'. One is a proper noun, one isn't. Other people do this different ways, it doesn't really matter which way you do it as long as you are consistent. Here we do it this way.