Web Education community group style guide

From Web Education Community Group
Revision as of 18:56, 24 May 2012 by Jswisher (Talk | contribs)

(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search

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.

Language

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, e.g., "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 let's say:

  • General grammar, spelling, and usage
  • 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 color spelt consistently between syntax and other wording will help reduce confusion. When updating an article, maintain consistency with the original text.
  • List commas: Use "Oxford" or "serial" commas before the conjunction in a series, e.g., "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 the site feel like a proper community.
  • Tense: use present tense unless a different tense is more really appropriate. Future tense is usually unnecessary in tech docs. "When you do X, the browser will do Y" works just as well in present tense: "When you do X, the browser does Y". Rarely, future tense is needed: "Someday, the spec will be finalised".
  • Other specific language forms:
    • FILL IN AS THEY ARISE

Code standards

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.
  • Including JavaScript: internal or external scripts are both ok, and can be used as appropriate.
    • 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.
  • Use proper indentation for HTML, CSS and JavaScript
    • 2 spaces for each nesting level in HTML.
    • 4 spaces (no tabs) for each nesting level in CSS and scripts.
  • Good practice JavaScript code should pass JSHint, with reasonable settings, including whitespace rules.
  • 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.

Vendor neutrality

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.

Accessibility

We are a very accessibility minded group, and all learning material and curricula should be accessible to people with disabilities and meet the W3C’s WCAG 2.0, at least Level AA. Material and examples should provide best practices for accessibility.

For content accessibility guidelines, see:

Learning about accessibility:

Internationalisation

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.