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).
No file extensions. This way we can change the format of a file without changing the content. Also, files can become folders later on.
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.
File names are lower case. It makes URLs consistent throughout the site and it's easier to remember the URL when case isn't an issue. 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 and FOO.
Hyphenate. Don't use StudlyCaps to separate words. You can't use upper case 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. Look at the site through it's tree structure rather than through the site navigation to get a better idea of where things go. The URI you're assigning to that file is more or less permanent, so it has to be forwards-compatible. Choose well, and run the new location past someone else before publicizing.
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.
You can change a file to a folder! If something logically belongs under what is right now a file, make it the index_html of a folder with the same name and put your file inside that folder. So if you want to add a related page, or split a long page into several sub-pages, or add an image, you can do that.
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.
This page, the mozilla.org 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 skin-writing guide to mozilla.org. Logically, it would go under /contribute/writing/guide/skins, 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 stylesheets (/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.
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.
Double-check links and don't rely on Zope's object
inheritance. For example, /contribute/hacking should not link to /dev with <a
href="dev">, because that resolves to /contribute/hacking/dev, which does not exist.
Instead of reporting a 404 error, Zope will walk up the tree until it
finds /dev--but now we've just returned
/contribute/hacking/dev, which makes
/dev live in two places at once. This is
bad. It confuses the browser, it confuses the
visitor, and it confuses the site's logic. Exploit Zope's object model
all you want behind the scenes, but don't expose it to the outside
world.
Be especially careful when linking to a nearby document. A link from
/contribute/writing to /contribute/evangelism is <a href="../evangelism/">, not <a href="evangelism">. (Remember -- /contribute/writing is really /contribute/writing/index_html.)
Use <a
name="anchor-name"> for anchors. Linking to an ID
isn't supported in many browsers.
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.
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.
All tags and attributes in lower-case. We may decide to switch to XML in the future, so get in the habit.
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.
Don't use . 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 . Corollary: use <pre> if you need to; not <tt> and a bucketful of non-breaking
spaces.
All pages must 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.
Any exceptions to this rule (e.g. <textarea wrap='x'>) must be approved by
the site webmaster.
Use semantic markup.
Semantic markup explains why something should be styled rather than
how it should be styled. This lets different stylesheets and
different browsers present the same idea differently and still be
correct. <p>, <sup>, and <em> are semantic elements. <b> and <i> are not. Stylistic information
belongs in the stylesheet, 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>.
There are a number of semantic classes defined in the Markup Reference. Use these instead of defining the element's presentation. Site stylesheets will assign appropriate presentation rules.
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).
Use classes defined in the Markup Reference. They already have styles associated with them, so you may not need to write any style rules.
Stylistic information is centralized into several site-wide stylesheets. This way, the site has a coherent look and feel and the formatting conventions are consistent. However, the site stylesheets 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 a tag or class. Zope allows "skinning" the site, which means different visitors can have different stylesheets. 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 skin might decide to make them italic serif.
No inline styles. The style
attribute is banned from mozilla.org pages. Use semantic markup and
either <link>ed stylesheets or
<style>.
If the same rules are used on more than one page, put them in a separate stylesheet file placed in the highest 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 stylesheets. 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.
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. 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 stylesheet--but try to do it without scripting, ok? For example, @import a stylesheet NS4.x shouldn't see.
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.
Avoid 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 first one is better than the second one:
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. If the upper-case is used for
style, let the stylesheet handle it. If you are talking about
SOME_RANDOM_C_TOKEN, make sure you mark it with <code>.
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 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. (Especially in your Member area.) 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.