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.
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 4 and Chapter 5. 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. If you use uppercase 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 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.
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.
Don't point to index.html directly. Point to the folder rather than the index.html file.
Use relative links whenever possible. This reflects the relationship between the two documents, and the link won't break if, for instance, you copy all the files to your disk.
Use <a
name="anchor-name">.
Linking to an ID isn't supported in many browsers. Also, anchors
should, like filenames, be lower case.
Anchors should not be empty. They should enclose some relevant fragment of text. For example, place the anchor tags around the full text of a heading to create an anchor for that section. If this is done right, highlighting all anchors' text can be a meaningful and useful styling.
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. Note that the site stylesheets already assign
no-breaking rules to code and filenames
and the like, so if you mark the text up properly, things will take
care of themselves.
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.)
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:
<p> to enclose
paragraphs, not <br> or <p> to separate them.
<b>, <big>, and/or <hr>.
You are encouraged to use our Templates, which have been designed with this in mind.
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.
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. Several presentational classes are required to be defined by each site-wide style for setting colors and backgrounds. Use these if you need color effects so there won't be any contrast problems. (Someone might design a style with green text on a black background, so you can't assume any color defaults.)
If for some reason you need to set specific colors:
!important.
background shorthand property, not
background-color or background-image.
.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.
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.
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 and
keywords to help indexing.
<meta name="keywords"
value="style guide, rules, guidelines, documentation">
<meta name="description"
value="Rules and guidelines for writing documents for
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).
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 (or, for that matter, Netscape.com).
Follow the branding guidelines when referring to Mozilla products.
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.
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.