Filenames

• Use descriptive file names. The ideal filename is succinct, specific enough to be descriptive, but general enough to accommodate change or expansion (e.g. becoming a folder). Don't just copy the page's title, as it isn't always appropriate for a filename.

• Avoid abbrev. It makes the URL that much harder to read and remember. We are not limited to 8.3 names, so make the file names as long as necessary (and no longer).

• Don't use page/part numbers. Don't name Chapter 4 ch4, because someday you may want to insert another chapter between Chapter 3 and Chapter 4. Name it after the chapter's title instead; this is also more descriptive. The only numbers in filenames should be dates and application version numbers.

• Filenames are lowercase. It makes URLs consistent throughout the site, and it's easier to remember the URL when case isn't an issue. The exception is documenting code: a doc on nsFoo should be nsFoo.html, not nsfoo.html, to match the code's casing. In no event should you have two files in the same directory that differ only in case: don't have Foo and FOO.

• Hyphenate. Don't use StudlyCaps to separate words. You can't use uppercase anyway. Use hyphens. Don't use underscores to separate words; underscores don't show up in underlined text.

• Don't use funny characters in file names. Stick to alphanumerics and hyphen. Our server is a Unix machine, and life gets somewhat more difficult if you use files with spaces, ampersands, quotes, and so on in their names. this-and-that is good. This&That.HTM is bad. You will royally screw anyone using a Macintosh (and Windows, I think) if you use colons, so don't do that.

• Avoid redundancy; don't over-qualify. dom/domref/dom-window-ref is too much—dom/reference/window is better.

Location

• Pick (or create) the most logical location for the document. Get a feel for the site's organization and fit the document where it most belongs.

• Use subfolders. If you have a few files that belong together, or if you expect to, make a subfolder that contains all the related files.

• A file's images go in its folder. Don't create an "images" folder. For example, a roadmap/ (roadmap/index.html) would put its diagram at roadmap/diagram. If the same image is used in several pages, then put it in the deepest common folder.

Code Format

• Use the ISO-8859-1 aka. Latin-1 character encoding. Represent characters that are outside the ISO-8859-1 repertoire (eg. typographically correct dashes and quotes) as decimal numeric character references. For example, encode the em dash (—) as —.

  Do not use references to Windows CP1252 code points even if they appear to work. That is, do not use — for em dash (or any other references to the 128…159 range).

• Use short lines. Some HTML editors like to produce documents that only insert line breaks in the HTML source at the ends of paragraphs. Don't do that. Use editors that give the HTML source sensibly short lines. If every paragraph is one long line, then diff is mostly useless (since diff is line-oriented.) Also there's always the chance that some random Unix utility is going to blow a buffer. Don't go there.

• Lowercase is preferred (but not required) for HTML tags and attributes.

• Don't use   unnecessarily. The fact of life of HTML is that sentences don't end in two spaces. Accept it. Don't try to work around it by using  . Corollary: use <pre> if you need to; not <tt> and a bucketful of non-breaking spaces.

Validation

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.)

Markup

• Use semantic markup. Semantic markup explains why something should be styled rather than how it should be styled. This lets different style sheets and different browsers present the same idea differently and still be correct. <p>, <code>, and <em> are semantic elements. <b> and <i> are not. Stylistic information belongs in the style sheet, not the markup. Nearly everything else is corollary. So:

  • Presentational markup is discouraged on mozilla.org even if it's allowed in HTML 4.01 Strict.
  • Use <p> to enclose paragraphs, not <br> or <p> to separate them.
  • Use Headings for headings, not an arbitrary combination of <b>, <big>, and/or <hr>.
  • Don't use tables for layout. Tables are for tabular data. Text columns are not tabular data.

  You are encouraged to use the markup conventions defined in our Markup Reference if you want a richer presentation.

  Recommended Reading: "Structured and Semantic Markup" from DocBook: The Definitive Guide (in Chapter 1) It's about 5 pages in the print version (4 pages printed), and worth the few minutes it takes to read.

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.

• Don't depend on any particular presentation for an element or class. HTML allows for alternate styles, which means different visitors can use different style sheets. You can depend on a set of sensible style rules, but don't depend on, e.g. all filenames being rendered in a monospaced font. A style might decide to make them italic serif.

• No inline styles. The style attribute is banned from mozilla.org pages with two exceptions: float and clear. Use semantic markup and either <link>ed style sheets or <style>.

• If the same rules are used on more than one page, put them in a separate style sheet file placed in the deepest folder common to these files.

• Avoid creating presentational classes. class="center" is no better than align="center".

• Do not set font-family. The font is handled by site style sheets. Other font properties are allowed, but don't change the font for the entire page (e.g. don't set font-size: small on <body>).

• Avoid setting any colors on individual pages.

  If for some reason you need to set specific colors:

  • Make sure you reset all the element's children as well.
  • Make color rules !important.
  • Never set a text color without also setting a background color, and vice versa.
  • Use the background shorthand property, not background-color or background-image.
  • If you're using a background image, also set a matching background color.

  .class {
      color: black !important;
      background: gray url(slate.gif) !important;
  }
  .class * {
      color: inherit !important;
      background: transparent !important;
  }

• Make sure multiple window sizes work. Resize the window, both narrow and wide. Another common mistake made by people using HTML editors is the presence of random <br> tags at the ends of lines.

• Pages must look decent in NS4+, MSIE4+, and Mozilla. Try to avoid exposing bugs in their CSS support; at the very least, make the page legible. A very useful resource is Eric Meyer's Master Compatibility Chart. If you must, block a problem browser from accessing your style sheet—but try to do it without scripting, ok? For example, @import a style sheet NS4.x shouldn't see or block out sections with the comment hack.

Meta Information

• Each document's author should be listed at the top. If it's a communal document, or an index, it's ok to leave the author off. But if it's a document with real content, it should list a way of contacting the author and providing feedback. Anonymity is bad.

  Look at the top of the document you're reading right now for the suggested format.

• Add meta description to help indexing. The description text should be an abstract of the page. If you're adding a keywords tag as well, pick keywords that you would use if you forgot the URI and were searching for the page, not just any remotely relevant word that comes to mind.

  <meta name="description"
        content="Rules and guidelines for writing documents on
               mozilla.org">
          

• Use <link> elements to link to related documents. It will improve the navigation for visitors using a browser (like Mozilla) that supports this HTML 2.0 feature. <link> denotes relationships between the entire page and another resource (as opposed to <a>, which is a context link; the relationship denoted applies to the immediate context of the anchor element).

Writing Form

• Avoid all caps. If the uppercase is used for style (e.g. for emphasis), let the style sheet handle it. If you are talking about SOME_RANDOM_C_TOKEN, make sure you mark it with <code>.

• mozilla.org is spelled in lowercase. The name of the application is Mozilla. It is a proper noun, and is therefore capitalized. The name of the organization is mozilla.org. It is a host name, and therefore, is lowercase. Even if it is at the beginning of a sentence, it should always be lowercase. If it bothers you to begin a sentence with a lowercase word, rephrase the sentence. (It's not hard.) Never type Mozilla.org.

• Use proper capitalization for titles and headings. This keeps capitalization consistent throughout mozilla.org. Also, although CSS can manipulate case, it can't do proper capitalization—so that needs to be written in.

• Use a spell checker. Say no more.

Writing Style

• Eschew marketing obfuscation. These are technical documents, folks. One of the things that people seem to like best about the existing content on mozilla.org is that it is written by people, for people, without bluster or self-promotion.

  When describing something, don't tell people how great it is. Don't tell them how useful it is. Tell them what it does. Tell them what it's for.

  Don't use buzzwords. Instead, say what you mean. Never use a long word where a short one would do. If it's possible to cut a word out, cut it out.

  Read George Orwell's Politics and the English Language. Read it again. Have it tattooed on the inside of your eyelids.

• Separate technical and religious topics. It is ok to publish documents which advocate potentially controversial ideas or approaches. However, it is generally better if such advocacy not be in the same document as technical information. For example, a document explaining what you have to do in order to successfully use C++ is a good thing; and a document arguing that you should not use C++ is also a good thing; however, they should not be the same document, because the controversial part might cause the readers to disregard the factual, non-controversial part, and miss out on important information.

• Speak for yourself. You don't speak for mozilla.org. Don't make promises about what mozilla.org will or will not do in the future. Hedge your bets with words like might or (sometimes) probably.

  Be careful with the word we. It would be bad if you made some assertion about what mozilla.org (as a whole) believes or desires or likes, only to find that there are others in the organization who disagree.

  Also, if you are employed to work on Mozilla, keep in mind that you likely wear two hats: your company hat, where you are concerned with shipping branded software; and your mozilla.org hat, where you are concerned with shipping source code on which other developers can base their own works. These two jobs are not the same, and you should be careful not to conflate the two.

• Don't play lawyer. Sometimes you may find yourself writing something about what is or is not allowed by the terms of the NPL, MPL, or some other license. Be very, very careful. It's probably best to say nothing at all, but if you must, you should defer to the authority of the license itself. Unless you actually are a lawyer, you're not qualified to interpret what it says, and you don't want to inadvertently say something that might get either mozilla.org or your employer into trouble.