Documentation Style Guide

Jamie Zawinski and fantasai

Here are some basic style guidelines for writing content to be hosted on Some are important, some are arbitrary, but please follow these guidelines in the name of consistency.

  1. Adding Files
    1. Filenames
    2. Location
    3. Example
  2. Linking, Anchors, and URLs
  3. Page Code
    1. Code Format
    2. Validation
    3. Markup
    4. Adding Style
  4. Content
    1. Meta Information
    2. Writing Form
    3. Writing Style

Adding Files



This page, the Style Guide, is located at /contribute/writing/guide. It's a guide (guide) describing how to contribute (contribute) by writing (writing). I chose not to make it style-guide because I might decide to expand it someday, and /contribute/writing/guide is descriptive enough in this case.

For example, I might decide to add a site-style-writing guide to Logically, it would go under /contribute/writing/guide/styles, so I would change /contribute/writing/guide to /contribute/writing/guide/index.html and put the file under the /contribute/writing/guide folder. Later, I might decide to split this guide up into several pages—one for location (/contribute/writing/guide/location), another for markup style (/contribute/writing/guide/markup), another for style sheets (/contribute/writing/guide/stylesheets), and another for content/writing style (/contribute/writing/guide/content. Now /contribute/writing/guide/index.html becomes a table of contents for all the pages under /contribute/writing/guide. Everything fits as if it were designed that way from the start and I'm not leaving any broken links because I made all my URIs forwards-compatible.

Linking, Anchors, and URLs

Page Code

Code Format


All new pages should validate as HTML 4.01 Strict using the W3C Validator. This ensures that the page doesn't have syntax errors, that it can be processed by all sorts of more obscure browsers, and that it doesn't use the presentational markup deprecated in HTML 4.0. Also, we're making one of the most standards-compliant browsers around. It would be bad show to have an incompliant website.

You can validate against HTML 4.01 Transitional instead, but only if there's a good reason. (The <font> tag is not a good reason.)


Adding Style

Check the classes defined in the Markup Reference first. The Reference defines a number of commonly-used classes that already have styles associated with them, so you may not need to write any style rules. Also, if you think something's missing from the Reference, file a bug asking fantasai to add it instead of working around the deficiency in your corner of the site.

Localized Style Rules

Stylistic information is centralized into several site-wide style sheets. This way, the site has a coherent look and feel and the formatting conventions are consistent. However, the site style sheets can't handle everything, so some pages may need to incorporate additional rules for local use or to handle specific page layouts.


Meta Information

Writing Form

Writing Style