Web Education community group style guide
From Web Education Community Group
Style guidelines for the W3C Web Education Community Group
The learning material and curricula published by the W3C Web Education Community Group (hereafter termed "WebEdu CG") should follow the guidelines contained in this document as closely as possible, to ensure high quality and consistency throughout. In reality, some of the material will only loosely follow these guidelines — a lot of it will be imported from existing resources such as The Opera web standards curriculum, Mozilla developer network, Microsoft developer network, etc., and it isn't a good use of our time to go around dotting every "i" and crossing every "t" wrt specific language guidelines. We should however, try to follow them as much as is reasonably possible.
Throughout our material we should use an informal, conversational, but authoritative tone. We don't want the material to be too dry and academic, and there is nothing wrong with having some fun and including a few jokes, but we also want the tone to embody knowledge, authority and trust.
We want to strike a balance.
In terms of specific language guidelines, I don't want to impose too many, eg "Has to use US English," as there will be so many different authors on this project. But such guidelines are good to have to resolve uncertainties, so lets say:
- General grammar - refer to Chicago manual of style
- General English classification - US English. In particular, this is useful because English words that appear in code syntax are spelt in US english, so having words like
colorspelt consistently between syntax and other wording will help reduce confusion.
- List commas - oxford or serial comma, eg one, two, and three, not one, two and three.
- 1st person/3rd person - use "We"/"You" rather than "I", unless it really is a case that requires I, e.g. "I the author am telling you a personal anecdote". I find that "We"/"You" sounds more like the author and the readers working together, as peers, rather than the author talking down to the readers, which can come over as a bit patronising. A Peer relationship is more likely to put readers at ease and make it feel like a proper community.
- Tense - it makes more sense to use present tense unless a different tense is more appropriate.
- Other specific language forms:
- FILL IN AS THEY ARISE
The material is to be as forward thinking as possible, so we will be using the most modern practices and techniques available at any point for the main example. However, it does make sense to explain other, similar techniques that the reader may still encounter on the Web, in case they come across it and need to know what it is.
For example, the examples will all use the HTML5 doctype, but we will still explain what other doctypes look like because the reader will still meet them in the wild.
- Doctype: Always use one and make it HTML5, unless deliberately showing a retro example.
- HTML and CSS should be valid, unless deliberately showing a bad example.
- Comment: Use CSS 3 when validating CSS.
- Exception 1: Validator bugs.
- Exception 2: Prefixed experimental CSS features are allowed.
- Including CSS: always use internal or external stylesheets as appropriate, never inline styles, unless showing a bad practice example.
- Never use presentational elements or attributes, unless showing a bad practice example.
- Inline event handlers are not OK.
- HTML style: even thought it is ok to use loose coding styles in HTML5 documents, we will still use XHTML coding style unless demonstrating loose coding style specifically.
- We do use explicit closing tags and do not rely on implicit closing.
- Exception to that rule: We don't need to worry about closing slashes on empty elements.
- We use quotation marks for all attribute values, even though they may only be one word or a number.
- But we specifically allow shortened boolean attributes, since that will make code more readable and the possibility of making errors by mistake is very low.
- Use lowercase text for HTML markup
- CSS shorthand: Always use shorthand, except for the bits where shorthand and longhand are explained, or when specifically using a longhand property to override a single property set inside shorthand
- Always include all available vendor prefixes, when demonstrating experimental CSS features, the non-prefixed declaration should always be last.
- End all CSS declarations with a semicolon - ;
- Consider using CSS Lint in addition to the CSS validator.
- 2 spaces for each nesting level in HTML.
- 4 spaces (no tabs) for each nesting level in CSS and scripts.
- ADD MORE AS THEY ARISE!
Open standards bias
The material will have a W3C open standards bias, but err on the side of pragmatism. So for example, if the demand is there, it is ok to include material covering browser-specific technologies (eg Opera Unite APIs, or Mozilla XUL) or even proprietary technologies (such as Flash). However, these should be clearly marked as browser specific and therefore not the primary path to take, and they should be stored in their own section of the final publishing platform.
These resources will have contributions from many individuals and companies, including browser and tool vendors (such as Opera, Mozilla, Google, Adobe, etc.) However, the material should remain as neutral as possible: nothing should be included that unduly favours one tool over another (unless there is good reason), and code examples should always be made cross browser compatible as much as possible.
We are a very accessibility minded group, therefore all learning material and curricula (including associated examples) should be make accessible to people with disabilities in the following ways:
- All images should have appropriate alt text
- All video/audio content should have text transcripts available
- All content should have a reasonable colour contrast
- All tables should be made accessible with proper headings, captions, etc.
- All form elements should have appropriate labels that are associated with them with the "for" attribute.
- All functionality of the content should be accessible through keyboard.
- All functionality that relies on the hover pseudo class should also have a focus pseudo class to support devices without hover (feature phones, TV sets, touch screen devices).
- ADD MORE!
As a general guideline, we should try to make all content conformant with WCAG 2 AA.
Note: EOWG input on this appreciated.
Content should always be have primary language defined in an appropriate way (eg <html lang="es">), and we should investigate ways to make the final publishing platform properly localisable.
Note: More input needed here, Chris will ask Richard Ishida for input.