mozilla.org style guide
by Jamie Zawinski <jwz@mozilla.org>

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

Currently, files exist on mozilla.org which don't follow all of these rules. That's not a disaster; hopefully we will clean them up someday, but it's not urgent. What is most important is that new documents do follow these guidelines.

1. File naming and URLs.

   • Use descriptive file names.
     We are not limited to 8.3 names, so make the file names as long as necessary (and no longer.)

   • The HTML extension is .html.
     Not .htm. See 8.3, above.

   • File names are lower case.
     If you use upper case letters, have a very good reason for it. In no event should you have two files in the same directory that differ only in case: don't have ``Foo.html'' and ``FOO.html.''

   • 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.html'' 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.

   • Hyphenate.
     Don't use StudlyCaps to separate words. Use hyphens. File names aren't Pascal code. Don't use underscores to separate words. Use hyphens. File names aren't C code.

   • File names can be long, if necessary.
     In particular, it might be appropriate for file names to be longer than 32 characters. But note that if you check such files in, Macintosh users will be unable to check them out. If you must deal with files with names more than 31 characters in length, you will be doing so at the expense of Macintosh users.

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

   • Use index.html.
     All subdirectories should have ``index.html'' files.

     The index.html file should be the main document of the directory. That is, foobar/foobar.html is bad. foobar/index.html is good.

   • Don't point to index.html directly.
     When linking to pages, point to the directory rather than the index.html file. When linking to a directory, include the trailing slash in the URL. That is, <A HREF="foobar/"> is good, <A HREF="foobar/index.html"> is bad, <A HREF="foobar"> is bad.

   • Use relative links whenever possible.
     <A HREF="../../images/bit.gif"> is good. <A HREF="/images/bit.gif"> is bad.

2. HTML coding.
   

   • Use LF, not CR or CRLF.
     The standard linebreak character for documents on mozilla.org is hereby declared to be LF (decimal 10, octal 012, hex 0x0A.) Keep those CRs out of the CVS repository.

   • 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 ``cvs 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.

   • Don't use META tags.
     Composer likes to put in noise like this:

     <META

     HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=iso-8859-1">

     While a nice touch in theory, back here in the real world, that tag makes 3.0-vintage Navigators load the document twice and generally lose their minds. Don't go there. If you use Composer, take this junk out before publishing it.

   • Use Latin1.
     Don't use Windows-specific characters like open/close double-quotes or long-dash. Don't use Mac-specific characters either. Make sure all characters you use are ISO-8859/1, AKA Latin1.

   • Don't use &nbsp;.
     This is another hateful artifact of Composer: 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 &nbsp;. For one thing, most versions of Mozilla have a bug that causes &nbsp; to display as a random printable character when the locale is set to Japanese. Corollary: use <PRE> if you need to; not <TT> and a bucketful of non-breaking spaces.

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

     When resizing the window to be narrow, you may find that some words are too long (for example, hyphenated phrases, pathnames, or URLs.) In these cases, use the <WBR> tag to indicate the place where it is ok to wrap the line within the word.

3. Look and layout.
   

   • Specify document colors.
     All pages must specify their foreground, background, and link colors. These are the colors you should use:

     <BODY

     BGCOLOR="#FFFFFF" TEXT="#000000" LINK="#0000EE" VLINK="#551A8B" ALINK="#FF0000">

   • Don't use <FONT FACE="...">.
     The default fonts chosen by the user are just fine, thanks.

   • Be careful with table cell colors.
     If you specify the background color of a table cell, you must use a light color. Don't try to produce light text on a dark background. While this might look better in recent browsers, in older browsers, people will end up seeing light text on a light background -- this is because <FONT COLOR="..."> has been supported since version 1.1, but <TD BGCOLOR="..."> has only been supported since version 3.0.

   • Use the Mozilla menu.
     Wrap your pages with the Mozilla menu. This is the default: pages can be explicitly not wrapped by listing them in the NOWRAP file in the same directory; but you should avoid doing that unless you've got a really good reason. (Note: don't include the HTML for the menu in your files directly! It's added automatically.)

   • Use indentation.
     If you're writing a document that has sections and subsections, indent the subsections using <UL> or <DL>. This is a taste thing, but I find documents that only signify headings and subheadings via font size (through <H2>, <H3>, etc) to be hard to read. For example, I find outdented headings to add a lot of clarity:

     section a All work and no play makes Jack a dull boy. All work and no play makes Jack a dull boy. All work and no play makes Jack a dull boy. subsection a.1 All work and no play makes Jack a dull boy. All work and no play makes Jack a dull boy. All work and no play makes Jack a dull boy. All work and no play makes Jack a dull boy. subsection a.2 All work and no play makes Jack a dull boy. All work and no play makes Jack a dull boy. All work and no play makes Jack a dull boy. All work and no play makes Jack a dull boy. section b All work and no play makes Jack a dull boy. All work and no play makes Jack a dull boy. All work and no play makes Jack a dull boy. All work and no play makes Jack a dull boy.

   • No adjacent headings.
     If you have a heading, and a subheading under it, put some intervening text between the two describing the section, and thereby introducing the set of subsections. Not only is this proper style, it also improves readability. The one on the left is better than the one on the right:

     section a All work and no play makes Jack a dull boy. All work and no play makes Jack a dull boy. subsection a.1 All work and no play makes Jack a dull boy. All work and no play makes Jack a dull boy. subsection a.2 All work and no play makes Jack a dull boy. All work and no play makes Jack a dull boy.

     section a subsection a.1 All work and no play makes Jack a dull boy. All work and no play makes Jack a dull boy. subsection a.2 All work and no play makes Jack a dull boy. All work and no play makes Jack a dull boy.

   • Use vertical whitespace.
     Composer seems to like to strip out <P> before <LI>, meaning that instead of something easy to read like the left column below, you end up with something squashed and inconsistent like the right column. Don't let that happen.

     All work and no play makes Jack a dull boy. All work and no play makes Jack a dull boy. All work and no play makes Jack a dull boy. All work and no play makes Jack a dull boy. All work and no play makes Jack a dull boy. All work and no play makes Jack a dull boy. All work and no play makes Jack a dull boy. All work and no play makes Jack a dull boy. All work and no play makes Jack a dull boy. All work and no play makes Jack a dull boy. All work and no play makes Jack a dull boy. All work and no play makes Jack a dull boy.

     All work and no play makes Jack a dull boy. All work and no play makes Jack a dull boy. All work and no play makes Jack a dull boy. All work and no play makes Jack a dull boy. All work and no play makes Jack a dull boy. All work and no play makes Jack a dull boy. All work and no play makes Jack a dull boy. All work and no play makes Jack a dull boy. All work and no play makes Jack a dull boy. All work and no play makes Jack a dull boy. All work and no play makes Jack a dull boy. All work and no play makes Jack a dull boy.

   • Avoid all caps.
     I find all-upper-case words in variable-width fonts to be unattractive. If you are talking about SOME_RANDOM_C_TOKEN, it's probably better to use <TT> for it, so that it shows up as SOME_RANDOM_C_TOKEN instead.

     Generally, I try to put all C tokens in <TT>, even lower case ones. Some people prefer bold or italic, but those also look bad with upper-case words.

   • mozilla.org is spelled in lower case.
     The name of the browser 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 lower case. Even if it is at the beginning of a sentence, it should always be lower case. If it bothers you to begin a sentence with a lower case word, rephrase the sentence (it's not hard.) Never type Mozilla.org (or, for that matter, Netscape.com.)

   • Use a spell checker.
     Say no more.

4. Content.
   

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

   • 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, nor do you speak for Netscape. 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.

     Don't make promises about what mozilla.org or Netscape will or will not do in the future. Hedge your bets with words like ``might'' or (sometimes) ``probably.''

     Also, if you are a Netscape employee, keep in mind that you likely wear two hats: your Netscape hat, where you are concerned with shipping Netscape Navigator end-user 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 Netscape into trouble.