Websites/Guides/Style: Difference between revisions

From MozillaWiki
Jump to navigation Jump to search
(Replaced content with "Please visit the [http://www.mozilla.org/en-US/styleguide/ One Mozilla style guide] for the latest and greatest details on our websites, logos and many other fun topics. For...")
 
(One intermediate revision by one other user not shown)
Line 1: Line 1:
= mozilla.org Style Guide =
Please visit the [http://www.mozilla.org/en-US/styleguide/ One Mozilla style guide] for the latest and greatest details on our websites, logos and many other fun topics.


by Jamie Zawinsky and fantasai
For Mozilla history buffs, the now-outdated content that was formerly on this page has been archived [https://wiki.mozilla.org/Websites/Guides/Style/Archive here].
 
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.
 
== Adding Files ==
 
=== 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 <code>ch4</code>, 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 <code>nsFoo</code> should be <code>nsFoo.html</code>, not <code>nsfoo.html</code>, 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 <code>Foo</code> and <code>FOO</code>.
 
'''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. <code>this-and-that</code> is good. <code>This&That.HTM</code> 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.''' <code>dom/domref/dom-window-ref</code> is too much—<code>dom/reference/window</code> 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. 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.
 
'''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 <code>roadmap/</code> (<code>roadmap/index.html</code>) would put its diagram at <code>roadmap/diagram</code>. If the same image is used in several pages, then put it in the deepest common folder.
 
=== Linking, Anchors, and URLs ===
 
'''Don't point to index.html directly.''' Point to the directory rather than the <code>index.html</code> file. (Include the trailing slash.)
 
'''Use relative links whenever practical.''' This reflects the relationship between the two documents, and the link won't break if, for instance, someone copies the documents to a test site.
 
'''Use id="anchor-name" for intra-page anchors.''' Also, anchors should, like filenames, be lower case.
 
'''Anchors should not be empty.''' They should enclose some relevant fragment of text. For example, to create an anchor for a section add the id attribute to the enclosing section or div tag (if there is one) or to the heading tag itself (if there isn't). If this is done right, styling the anchoring element can be a meaningful and useful styling.
 
== Code ==
=== Code Format ===
 
'''Use UTF-8.''' Use HTML named entities or Unicode numerical codes for escapes, like &amp;#8212; or &amp;mdash; for an em dash. Do not use references to Windows CP1252 code points even if they appear to work. That is, do not use &#151; 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 &amp;nbsp; 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 &nbsp;. Corollary: use <code>&lt;pre&gt; if you need to; not <code>&lt;tt&gt;</code> and a bucketful of non-breaking spaces.
 
=== Validation ===
 
'''All new pages should validate as HTML 4.01 Strict or HTML5''' using the [http://validator.w3.org/ 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.
 
=== 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.  <code>&lt;p&gt;</code>, <code>&lt;code&gt;</code>, and <code>&lt;em&gt;</code> are semantic elements. <code>&lt;b&gt;</code> and <code>&lt;i&gt;</code> 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 <code>&lt;p&gt;</code> to ''enclose'' paragraphs, not <code>&lt;br&gt;</code> or <code>&lt;p&gt;</code> to separate them.
*Use [http://www.w3.org/TR/html4/struct/global.html#h-7.5.5 Headings] for headings, not an arbitrary combination of <code>&lt;b&gt;</code>, <code>&lt;big&gt;</code>, <code>&lt;hr&gt;</code>, and/or CSS.
*Don't use tables for layout. Tables are for tabular data. Text columns are not tabular data.
 
Recommended Reading: [http://www.oasis-open.org/docbook/documentation/reference/html/ch01.html#AEN367 Structured and Semantic Markup] from <cite>DocBook: The Definitive Guide</cite> (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 ===
 
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. Reuse the site's markup conventions. If there's a commonly-used construct that's missing from the global style sheets, file a bug to add it there instead of working around the deficiency in your corner of the site.
 
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. If that's the case with you:
 
'''Don't depend on any particular presentation for an element or class.''' Our content outlasts our site designs. 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>.
 
'''Share common styles.''' If the same rules are used on more than one page, but not globally, put them in a separate style sheet file placed in the deepest folder common to those 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 <code>font-size: small</code> on <code>&lt;body&gtl;</code>).
 
'''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 <code>!important</code>.
*Never set a text color without also setting a background color, and vice versa.
*Use the <code>background</code> shorthand property, not <code>background-color</code> or <code>background-image</code>.
*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;
  }
 
'''Pages must be legible in NS4+, MSIE6+, and Mozilla, with or without CSS or JS.''' We're trying to upgrade the Web here. Don't block the dark forgotten reaches who haven't seen the light of the latest shiny, or have access problems and are jumping through hoops to reach us. It doesn't have to be pretty, but it has to work.
 
'''Make sure multiple window sizes work.''' Resize the window, both narrow and wide. (No, ''really'' narrow: 900 pixels is not narrow, it's normal.) Another common mistake made by people using HTML editors is the presence of random <code>&lt;br&gt;</code> tags at the ends of lines.
 
== Content ==
 
=== 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 <code>SOME_RANDOM_C_TOKEN</code>, make sure you mark it with <code>&lt;code&gt;</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.

Latest revision as of 22:33, 25 October 2012

Please visit the One Mozilla style guide for the latest and greatest details on our websites, logos and many other fun topics.

For Mozilla history buffs, the now-outdated content that was formerly on this page has been archived here.

Retrieved from "https://wiki.allizom.org/index.php?title=Websites/Guides/Style&oldid=482951"