Writing style guide - The MDN project 编辑

To present documentation in an organized, standardized, and easy-to-read manner, the MDN Web Docs style guide describes how text should be organized, spelled, formatted, and so on. These are guidelines rather than strict rules. We are more interested in content than formatting, so don't feel obligated to learn the style guide before contributing. Do not be upset or surprised, however, if an industrious volunteer later edits your work to conform to this guide.

The language aspects of this guide apply primarily to English-language documentation. Other languages may have (and are welcome to create) style guides. These should be published as subpages of the localization team's page.

For style standards that apply to content written for sites other than MDN, refer to the One Mozilla style guide.

Basics

The best place to start in any extensive publishing style guide is with some very basic text standards to help keep documentation consistent. The following sections outline some of these basics to help you.

Page titles

Page titles are used in search results and are also used to structure the page hierarchy in the breadcrumb list at the top of the page. The page title (which is displayed at the top of the page and in the search results) can be different from the page "slug", which is the portion of the page's URL following "<locale>/docs/".

Title and heading capitalization

Page titles and section headings should use sentence-style capitalization (only capitalize the first word and proper nouns) rather than headline-style capitalization:

• Correct: "A new method for creating JavaScript rollovers"
• Incorrect: "A New Method for Creating JavaScript Rollovers"

We have many older pages that were written before this style rule was established. Feel free to update them as needed if you like. We're gradually getting to them.

Choosing titles and slugs

Page slugs should be kept short. When creating a new level of hierarchy, the new level's component in the slug should just be a word or two.

Page titles, on the other hand, may be as long as you like, within reason, and they should be descriptive.

Creating new subtrees

When you need to add some articles about a topic or subject area, you will typically do so by creating a landing page, then adding subpages for each of the individual articles. The landing page should open with a paragraph or two describing the topic or technology, then provide a list of the subpages with descriptions of each page. You can automate the insertion of pages into the list using some macros we've created.

For example, consider the JavaScript guide, which is structured as follows:

• JavaScript/Guide – Main table-of-contents page
• JavaScript/Guide/JavaScript Overview
• JavaScript/Guide/Functions
• JavaScript/Guide/Details of the Object Model

Try to avoid putting your article at the top of the hierarchy, which slows the site down and makes search and site navigation less effective.

Note: Adding articles requires page creation privileges.

General article content guidelines

When writing any document, it's important to know how much to say. If you ramble on too long, or provide excessive detail, the article becomes tedious to read and it will rarely be used. Getting the amount of coverage right is important for several reasons. Among those reasons: ensure that the reader finds the information they truly need, and provide enough quality material for search engines to adequately analyze and rank the article.

We'll discuss the former (providing the information the reader may need) here. To learn more about ensuring that pages are properly classified and ranked by search engines, see the article How to write for SEO on MDN.

The goal is to write pages that include all the information that readers may need without going into too much details. Following are some recommendations in this area.

Consider your audience

Keep in mind that these are guidelines. Some of these tips may not apply in every case. Certainly keep your article's audience in mind. For example, article on advanced network techniques likely doesn't need to go into as much detail about basic networking concepts as the typical article on networking.

Provide a useful summary

Make sure the article's summary—that is, the opening paragraph or paragraphs before the first heading—provides enough information for the readers to understand if the article is likely to be covering what they're interested in reading about.

In a guide or tutorial content, the summary should let the reader know what topics will be covered and what they're already expected to know, if anything. It should mention the technologies and/or APIs that are being documented or discussed, with links to related information, and it should offer hints to situations in which the article's contents might be useful.

Example: Too short!

This example of a summary is far too short. It leaves out too much information, such as what it means exactly to "stroke" text, where the text is drawn, and so forth.

CanvasRenderingContext2D.strokeText() draws a string.

Example: Too long!

Here, we've updated the summary, but now it's far too long. Too much details are included, and the text gets far too much into describing other methods and properties.

Instead, the summary should focus on the strokeText() method, and should refer to the appropriate guides where the other details are described.

When called, the Canvas 2D API method CanvasRenderingContext2D.strokeText() strokes the characters in the specified string beginning at the coordinates specified, using the current pen color. In the terminology of computer graphics, "stroking" text means to draw the outlines of the glyphs in the string without filling in the contents of each character with color.

The text is drawn using the context's current font as specified in the context's font property.

The placement of the text relative to the specified coordinates are determined by the context's textAlign, textBaseline, and direction properties. textAlign controls the placement of the string relative to the X coordinate specified; if the value is "center", then the string is drawn starting at x - (stringWidth / 2), placing the specified X-coordinate in the middle of the string. If the value is "left", the string is drawn starting at the specified value of x. And if textAlign is "right", the text is drawn such that it ends at the specified X-coordinate.

(etc etc etc...)

You can, optionally, provide a fourth parameter that lets you specify a maximum width for the string, in pixels. If you provide this parameter, the text is compressed horizontally or scaled (or otherwise adjusted) to fit inside a space that wide when being drawn.

You can call the fillText() method to draw a string's characters as filled with color instead of only drawing the outlines of the characters.

Example: Much better!

Here we see a much better overview for the strokeText() method.

The CanvasRenderingContext2D method strokeText(), part of the Canvas 2D API, strokes—that is, draws the outlines of—the characters of a specified string, anchored at the position indicated by the given X and Y coordinates. The text is drawn using the context's current font, and is justified and aligned according to the textAlign, textBaseline, and direction properties.

For more details and further examples, see Text in Drawing graphics in the Learning Area as well as our main article on the subject, Drawing text.

Include all relevant examples

It's important to ensure that you use examples to clarify what every parameter is used for, and to clarify any edge cases that may exist. You should also use examples to demonstrate solutions for common tasks, and you should use examples to demonstrate solutions to problems that may arise.

In general it is expected that most of the pages will include examples, and that most of them will include more than one example.

Each example should be preceded by text explaining what the example does and anything the reader should know before beginning to read or try out the example.

Code Examples

Each piece of code should include an explanation of how it works. Keep in mind that it may make sense to break up a large piece of code into smaller portions so they can be described individually.

The text following each piece of code should explain anything relevant, using an appropriate level of detail:

• If the code is very simple and doesn't really use directly anything related to the API being documented, you may only give a quick summary of what it is and why it's there.
• If the code is intricate, uses the API being documented, or is technically creative, you should provide a more detailed explanation.

When using the live sample system, it's helpful to be aware that all of the <pre> blocks in the area that contains the sample are concatenated together before running the example, which lets you break any or all of the HTML, CSS, and JavaScript into multiple segments, each optionally with its own descriptions, headings, and so forth. This makes documenting code incredibly powerful and flexible.

Overly-short articles are hard to find

If an article is "thin"—that is, too short—it may not be indexed properly (or at all) by search engines. As a rule of thumb, the article's body text should be at least 250–300 words. Don't artificially inflate a page, but treat this guideline as a minimum target length when possible.

Sections, paragraphs, and newlines

The Enter (or Return) key on your keyboard starts a new paragraph. To insert a newline, rather than a new paragraph (that is, to create a <br> instead of a <p>), hold down the Shift key while pressing Enter.

When a new paragraph starts a new section, a header should be added.  Use heading levels in decreasing order: <h2> then <h3> then <h4>, without skipping levels.

H2 is the highest level allowed because H1 is reserved for the page title. If you need more than three or four levels of headers, consider breaking up the article into several smaller articles with a landing page, and linking them together using the following macros: Next, Previous, and PreviousNext.

Heading dos and donts

• Don't create single subsections. Don't subdivide a topic into a single subtopic. It's either two subheadings or more, or none at all.
• Don't use styles and classes within headings. This includes the <code> element for code terms. So don't make a heading "Using the SuperAmazingThing interface". It should instead just be "Using the SuperAmazingThing interface".
• Avoid using macros within headings (except for certain macros that are specifically designed to be used in headings).
• Don't create "bumping heads." These are headings followed immediately by a subheading, with no content text in between. This doesn't look good, and leaves readers without any explanatory text at the beginning of the outer section.

Lists

Lists should be formatted and structured uniformly across all pages. Individual list items should be written with suitable punctuation, regardless of the list format. However, depending on the type of the list you are creating, you will want to adjust your writing as described in the sections below.

Bulleted lists

Bulleted lists should be used to group related pieces of concise information. Each item in the list should follow a similar sentence structure. Phrases and sentences in bulleted lists should include standard punctuation. A period must appear at the end of each sentence in a bulleted list, including the item's final sentence, just as would be expected in a paragraph.

An example of a correctly structured bulleted list:

In this example we should include:

• A condition, with a brief explanation.
• A similar condition, with a brief explanation.
• Yet another condition, with some further explanation.

Note how the same sentence structure repeats from bullet to bullet. In this example, each bullet point states a condition followed by a comma and a brief explanation, and each item in the list ends with a period.

Numbered lists

Numbered lists are used primarily to enumerate steps in a set of instructions. Because instructions can be complex, clarity is a priority, especially if the text in each list item is lengthy. As with bulleted lists, follow standard punctuation usage.

An example of a correctly structured numbered list:

In order to correctly structure a numbered list, you should:

1. Open with a heading or brief paragraph to introduce the instructions. It's important to provide the user with context before beginning the instructions.
2. Start creating your instructions, and keep each step in its own numbered item. Your instructions may be quite extensive, so it is important to write clearly and use correct punctuation.
3. After you have finished your instructions, follow the numbered list with a brief closing summary or explanation about the expected outcome upon completion.

This is an example of writing a closing explanation. We have created a short numbered list that provides instructive steps to produce a numbered list with the correct formatting.

Note how the items in numbered lists read like short paragraphs. Because numbered lists are routinely used for instructional purposes, or to walk someone through an orderly procedure, be sure to keep each item focused: one numbered item per step.

Text formatting and styles

Use the "Formatting Styles" drop-down list to apply predefined styles to selected content.

The "Note Box" style is used to call out important notes, like this one. Similarly, the "Warning Box" style creates warning boxes like this.

Unless specifically instructed, do not use the HTML style attribute to manually apply a style. If you can't do it using a predefined class, ask for help in the MDN discussion forum.

Code sample style and formatting

Note: This section deals with the styling/formatting of code as it appears on an MDN article. If you want guidelines on actually writing code examples, see our Code sample guidelines.

Tabs and line breaks

Use two spaces per tab in all code examples. Indent the code cleanly, with open-brace ("{") characters on the same line as the statement that opens the block. For example:

if (condition) {
  /* handle the condition */
} else {
  /* handle the "else" case */
}

Long lines shouldn't be allowed to stretch off horizontally to the extent that they require horizontal scrolling to read. Instead, break long lines at natural breaking points. Some examples follow:

if (class.CONDITION || class.OTHER_CONDITION || class.SOME_OTHER_CONDITION
       || class.YET_ANOTHER_CONDITION ) {
  /* something */
}

var toolkitProfileService = Components.classes["@mozilla.org/toolkit/profile-service;1"]
                           .createInstance(Components.interfaces.nsIToolkitProfileService);

Inline code formatting

Use the "Code" button (labeled with two angle brackets "<>") to apply inline code-style formatting to function names, variable names, and method names. (This uses the <code> element). For example: "the frenchText() function".

Method names should be followed by a pair of parentheses. For example, doSomethingUseful(). The parentheses help differentiate methods from other code terms.

Syntax highlighting

A line or multiple lines of code should be formatted using syntax highlighting rather than the <code> element. Select the appropriate language from the language list button (the one with the two code blocks), as seen in the screenshot to the right. This will insert a preformatted code box with line numbers and syntax highlighting for the chosen language.

Note: Do not use the <code> element inside the <pre> block!

While this structure is used on some sites, we do not do so on MDN; nesting these elements will break certain aspects of our styling.

The following example shows text with JavaScript formatting:

for (let i = 0, j = 9; i <= 9; i++, j--)
  document.writeln("a[" + i + "][" + j + "]= " + a[i][j]);

If no appropriate language is available, use ("No Highlight" in the language menu). This will result in code without syntax highlighting:

x = 42;

Syntax definitions

When writing the syntax description section of a reference page, use the "Syntax Box" option in the "Styles" drop-down menu in the editor toolbar. This creates a specially-formatted box that is used specifically for syntax definitions, distinguishing them from other code blocks.

Blocks not referring to code

There are a some use cases where a <pre> block does not refer to code and doesn't have syntax highlighting nor line numbers. In such cases you should add a <pre> without a class attribute. For example, those cases include tree structures:

root/

  folder1/
    file1

  folder2/
    file2
    file3

To create preformatted content without syntax highlighting and line numbers click the "PRE" button in the toolbar. Then start to type the text.

Styling mentions of HTML elements

There are specific rules to follow when writing about HTML elements. These rules produce consistent descriptions of elements and their components. They also ensure correct linking to detailed documentation.

Element names

Use the HTMLElement macro, which creates a link to the page for that element. For example, writing {{HTMLElement("title")}} produces "<title>". If you don't want to create a link, enclose the name in angle brackets and use the "Inline Code" style (e.g., <title>).

Attribute names

Use "Inline Code" style to put attribute names in code font. Additionally, put them in bold face when the attribute is mentioned in association with an explanation of what it does, or the first time it is used in the article.

Attribute definitions

Use the htmlattrdef macro (e.g., {{htmlattrdef("type")}}) for the definition term, so that it can be linked to from other pages easily by using the htmlattrxref macro (e.g., {{htmlattrxref("type","element")}}) to reference attribute definitions.

Attribute values

Use the "Inline Code" style to apply <code> to attribute values, and don't use quotation marks around string values, unless needed by the syntax of a code sample.

For example: "When the type attribute of an <input> element is set to email or tel ..."

Latin abbreviations

In notes and parentheses

• Common Latin abbreviations (etc., i.e., e.g.) may be used in parenthetical expressions and notes. Use periods in these abbreviations, followed by a comma or other appropriate punctuation.
  • Correct: Web browsers (e.g., Firefox) can be used ...
  • Incorrect: Web browsers e.g. Firefox can be used ...
  • Incorrect: Web browsers, e.g. Firefox, can be used ...
  • Incorrect: Web browsers, (eg: Firefox) can be used ...

In running text

• In regular text (i.e., text outside of notes or parentheses), use the English equivalent of the abbreviation.
  • Correct: ... web browsers, and so on.
  • Incorrect: ... web browsers, etc.
  • Correct: Web browsers such as Firefox can be used ...
  • Incorrect: Web browsers e.g. Firefox can be used ...

Meanings and English equivalents of Latin abbreviations

Abbrev	Latin	English
cf.	confer	compare
e.g.	exempli gratia	for example
et al.	et alii	and others
etc.	et cetera	and so forth, and so on
i.e.	id est	that is, in other words
N.B.	nota bene	note well
P.S.	post scriptum	postscript

Always consider whether it's truly beneficial to use a Latin abbreviation. Some of these are used so rarely that many readers won't understand the meaning, and others are often confused with one another.

Also, be sure that you use them correctly, if you choose to do so. For example, be careful not to confuse "e.g." with "i.e.", which is a common error.

Acronyms and abbreviations

Capitalization and periods

Use full capitals and delete periods in all acronyms and abbreviations, including organizations such as "US" and "UN".

• Correct: XUL
• Incorrect: X.U.L.; Xul

Expansion

On the first mention of a term on a page, expand acronyms that are likely to be unfamiliar to users. When in doubt, expand it—or better yet, link it to the article or glossary entry describing the technology.

• Correct: "XUL (XML User Interface Language) is Mozilla's XML-based language..."
• Incorrect: "XUL is Mozilla's XML-based language..."

Plurals of acronyms and abbreviations

For plurals of acronyms or abbreviations, add s.

Don't use an apostrophe. Ever. Please.

• Correct: CD-ROMs
• Incorrect: CD-ROM's

"Versus", "vs.", and "v."

The contraction "vs." is preferred.

• Correct: this vs. that
• Incorrect: this v. that
• Incorrect: this versus that

Capitalization

Use standard English capitalization rules in body text, and capitalize "World Wide Web." It is acceptable to use lower case for "web" (used alone or as a modifier) and "internet".

This guideline is a change from a previous version of this guide, so you may find many instances of "Web" and "Internet" on MDN.

Feel free to change these as you are making other changes, but editing an article just to change capitalization is not necessary.

Keyboard keys should use sentence-style capitalization, not all-caps capitalization. For example, "Enter" not "ENTER". The only exception is that you can use "ESC" to abbreviate he "Escape" key.

Certain words should always be capitalized (such as trademarks which include capital letters), or words derived from the name of a person (unless it's being used within code, and code’s syntax requires lower-casing). Some examples:

• Boolean (named for English mathematician and logician George Boole)
• JavaScript (a trademark of Oracle Corporation, it should always be written as trademarked)
• Python, TypeScript, Django, and other programming languages and framework names

Contractions

Our writing style tends to be casual, so you should feel free to use contractions (e.g., "don't", "can't", "shouldn't"), if you prefer.

Pluralization

Use English-style plurals, not the Latin- or Greek-influenced forms.

• Correct: syllabuses, octopuses
• Incorrect: syllabi, octopi

Hyphenation

Hyphenate compounds should be used when the last letter of the prefix is a vowel and is the same as the first letter of the root.

• Correct: email, re-elect, co-op
• Incorrect: e-mail, reelect, coop

Gender-neutral language

To make the text as inclusive as possible, it is best to use gender-neutral language in any writing where gender is irrelevant to the subject matter. For example, if you are talking about the actions of a specific man, using "he"/"his" is fine; but if the subject is a person of either gender, "he"/"his" isn't appropriate.

Let's take the following example:

A confirmation dialog appears, asking the user if he allows the Web page to make use of his Web cam.

A confirmation dialog appears, asking the user if she allows the Web page to make use of her Web cam.

Both versions are gender-specific. To fix this, use gender-neutral pronouns:

A confirmation dialog appears, asking the user if they allow the Web page to make use of their Web cam.

MDN allows the use of this very common syntax (which is controversial among usage authorities) to make up for the lack of a neutral gender in English.

The use of the third-person plural as a gender neutral pronoun (that is, using "they," "them", "their," and "theirs") is an accepted practice, commonly known as "singular 'they.'"

You can use both genders:

A confirmation dialog appears, asking the user if he or she allows the web page to make use of his/her web cam.

Making the users plural:

A confirmation dialog appears, asking the users if they allow the web page to make use of their web cams.

The best solution, of course, is to rewrite and eliminate the pronouns:

A confirmation dialog appears, requesting the user's permission for web cam access.

A confirmation dialog box appears, which asks the user for permission to use the web cam.

This last example of dealing with the problem is arguably better. Not only is it grammatically more correct, but removes some of the complexity associated with dealing with genders across different languages that may have wildly different gender rules. This solution can make translation easier for both readers and localizers.

Numbers and numerals

Dates

For dates (not including dates in code samples) use the format "January 1, 1990".

• Correct: February 24, 2006
• Incorrect: February 24th, 2006; 24 February, 2006; 24/02/2006

Alternately, you can use the YYYY/MM/DD format.

• Correct: 2006/02/24
• Incorrect: 02/24/2006; 24/02/2006; 02/24/06

Decades

For decades, use the format "1990s". Don't use an apostrophe.

• Correct: 1990s
• Incorrect: 1990's

Plurals of numerals

For plurals of numerals add "s". Don't use an apostrophe.

• Correct: 486s
• Incorrect: 486's

Commas

In running text, use commas only in five-digit and larger numbers.

• Correct: 4000; 54,000
• Incorrect: 4,000; 54000

Punctuation

Serial comma

Use the serial comma. The serial (also known as "Oxford") comma is the comma that appears before the conjunction in a series of three or more items.

• Correct: I will travel on trains, planes, and automobiles.
• Incorrect: I will travel on trains, planes and automobiles.

This is in contrast to the One Mozilla style guide, which specifies that the serial comma is not to be used. MDN is an exception to this rule.

Apostrophes and quotation marks

Do not use "curly" quotes and quotation marks. On MDN, we only use straight quotes and apostrophes.

There are a couple of reasons for this.

1. We need to choose one or the other for consistency.
2. If curly quotes or apostrophes make their way into code snippets—even inline ones—readers may copy and paste them, expecting them to function (which they will not).

• Correct: Please don't use "curly quotes."
• Incorrect: Please don’t use “curly quotes.”

Spelling

For words with variant spellings, always use their American English spelling.

In general, use the first entry at Dictionary.com, unless that entry is listed as a variant spelling or as being primarily used in a non-American form of English. For example, if you look up "behaviour", you find the phrase "Chiefly British" followed by a link to the American standard form, "behavior". Do not use variant spellings.

• Correct: localize, behavior
• Incorrect: localise, behaviour

Terminology

HTML elements

Use "elements" to refer to HTML and XML elements, rather than "tags". In addition, they should almost always be wrapped in "<>", and should be in the <code> style.

When you reference a given element for the first time in a section, you should use the HTMLElement macro to create a link to the documentation for the element (unless you're writing within that element's reference document page).

• Correct: the <span> element
• Incorrect: the span tag

Parameters vs. arguments

The preferred term on MDN is parameters. Please avoid the term "arguments" for consistency whenever possible.

User interface actions

In task sequences, describe user interface actions using the imperative mood. Identify the user interface element by its label and type.

• Correct: Click the Edit button.
• Incorrect: Click Edit.

Voice

While the active voice is preferred, the passive voice is also acceptable, given the informal feel of our content. Try to be consistent, though.

Wiki markup and usage

Links

Links are a large part of what makes a wiki a powerful learning and teaching tool. Below you'll find some basic information, but you can find a complete guide to creating and editing links on MDN in our editor guide.

We encourage you to create appropriate links among articles; they help improve navigation and discoverability of content, and they provide important context to search engines like Google to help them provide better results. Every page should have a good set of links from words or phrases to other pages that expand upon the relevant ideas. This can be used both to define terms and to provide more in-depth or detailed documentation about a topic, or to connect to a related page that offers examples or information that may be of further interest.

You can easily create links not only among pages on MDN (internal links) but also to pages outside MDN (external links).

There are two ways to create links:

• You explicitly create a link using the Link button in the editor's toolbar—or by pressing Ctrl+K (Cmd+K on the Mac).
• Or, you can use MDN's powerful macro system to generate links automatically or based on an input value.

When deciding what text to use as a link, there are a few guidelines you can follow:

• Whenever a macro exists which will create the link you need, and you are able to do so, please do. Using macros to create links will not only help you get it right, but will allow future improvements to MDN to automatically be applied to your link.
• For an API name, use the entire string of the API term as written in your content. The easiest way to do this is to use the appropriate macro to construct a properly-formatted link for you.
• To link to a page defining or discussing a particular term, use only the term's name for the link's text; do not include additional text in the link. For example:
  • Correct: You can use JavaScript code to create dynamic applications on the Web.
  • Incorrect: You can use JavaScript code to create dynamic applications on the Web.
• Otherwise, when adding a useful link to prose, try to choose an action and object phrase, such as:
  • Correct: If you'd like to contribute to the Firefox project, your first step is to download and build Firefox.
  • Incorrect: If you'd like to contribute to the Firefox project, your first step is to download and build Firefox.

URL schemes

For security reasons, you should only create links that use the following schemes:

• http://
• https://
• ftp://
• mailto:

Others may or may not work, but are not supported and will probably be removed by editorial staff.

In particular, avoid the about: or chrome:// schemes, as they will not work.

Similarly, the javascript: scheme is blocked by most modern browsers, as is jar:.

Page tags

Tags provide meta information about a page. They may also indicate that a page has specific improvements needed to its content. Every page in the wiki should have tags.

You can find details on tagging in our How to properly tag pages guide.

The tagging interface lives at the bottom of a page while you're in edit mode, and looks something like this:

To add a tag, click in the edit box at the end of the tag list and type the tag name you wish to add. Tags will autocomplete as you type. Press Enter (or Return) to submit the new tag. Each article may have as many tags as needed. For example, an article about using JavaScript in AJAX programming might have both "JavaScript" and "AJAX" as tags.

To remove a tag, just click the little "×" icon in the tag.

Tagging pages that need work

In addition to using tags to track information about the documentation's quality and content, we also use them to mark articles as needing specific types of work.

Tagging obsolete pages

Use the following tags for pages that are not current:

Junk

Use for spam, pages created by mistake, or content that is so bad that it should be deleted. Pages with this tag are deleted from time to time.

Obsolete

Use for content that is technically superseded, but still valid in context. For example, this might be an HTML element that is obsolete in HTML5, but still valid in HTML 4.01.

You can also use the obsolete_header macro to put a prominent banner on the topic.

Archive

Use for content that is technically superseded and no longer useful. If possible, add a note to the topic referring readers to a more current topic.

For example, a page that describes how to use the Mozilla CVS repository should refer readers to a current topic on using Mercurial repos. (If no corresponding current topic exists, use the NeedsUpdate tag, and add an explanation on the Talk page.)

Pages with the Archive tag are eventually moved from the main content of MDN to the Archive section.

SEO summary

The SEO summary provides a short description of a page. It will be reported as a summary of the article to robots crawling the site, and will then appear in search results for the page. It is also used by macros that automate the construction of landing pages inside MDN itself. (In other words, it's not just for SEO.)

By default, the first paragraph of the page is used as the SEO summary. However, you can override this behavior by marking a section with the "SEO summary" style in the WYSIWYG editor.

Landing pages

Landing pages are pages at the root of a topic area of the site, such as the main CSS or HTML pages. They have a standard format that consists of three areas:

1. A brief overview (typically one paragraph) of what the technology is and how it's used. See Writing a landing page overview for tips.
2. A two-column list of links with appropriate headings. See Creating a page link list for guidelines.
3. An optional "Browser compatibility" section at the bottom of the page.

Creating a page link list

The link list section of an MDN landing page consists of two columns. These are created using the following HTML:

<div class="row topicpage-table">
  <div class="section">
    ... left column contents ...
  </div>
  <div class="section">
    ... right column contents ...
  </div>
</div>

The left column should be a list of articles, with an <h2> header at the top of the left column explaining that it's a list of articles about the topic (e.g., "Documentation and tutorials about foo"). This header should use the CSS class "Documentation".

Below that is a <dl> list of articles with each article's link in a <dt> block and a brief one-or-two sentence summary of the article in the corresponding <dd> block.

The right column should contain one or more of the following sections, in order:

Getting help from the community

This should provide information on Matrix chat rooms and mailing lists available on the topic. The heading should use the class "Community".

Tools

A list of tools the user can look at to help with the use of the technology described in this section of MDN. The heading should use the class "Tools".

Related topics

A list of links to landing pages for other, related, technologies of relevance. The heading should use the class "Related_Topics".

FIXME: Finish this once we finalize the landing page standards

Using and inserting images

It's sometimes helpful to provide an image in an article you create or modify, especially if the article is very technical.

To include an image:

1. Before uploading your image, please ensure that it's as small as possible by using an image optimization tool.
   • For bitmap images (JPG or PNG), consider a tool such as ImageOptim (macOS), TinyPNG (web service), or Trimage (Linux).
   • For SVG images, use the svgo tool to optimize the SVG file before sending it. The default configuration is fine.
2. Attach the desired image file to the article (at the bottom of every article in edit mode). If your artwork is a diagram in SVG format (which is ideal if there is text that may need to be localized), you can't upload it directly, but you can ask an MDN admin to do it for you.
3. Click the "insert image" button in the MDN documentation WYSIWYG editor.
4. In the WYSIWYG editor's drop-down list of attachments, select the newly created attachment that is your image.
5. Press the OK button.

Important: Remember to save any changes you've made before uploading an attachment to your article! The editor is closed during the upload process, and currently does not verify whether or not you wish to save your work when it does so.

Other references

Preferred style guides

If you have questions about usage and style not covered here, we recommend referring to the Microsoft Writing Style Guide—or, failing that, the Chicago Manual of Style. An unofficial crib sheet for the Chicago Manual of Style is available online.

Preferred dictionary

For questions of spelling, please refer to Dictionary.com. The spelling checker for this site uses American English. Please do not use variant spellings (e.g., use color rather than colour).

We will be expanding the guide over time, so if you have specific questions that aren't covered in this document, please post them on the MDN discussion forum, so we know what should be added.

MDN-specific

• Commonly-used macros on MDN, with explanations

Language, grammar, spelling

If you're interested in improving your writing and editing skills, you may find the following resources to be helpful.

• On Writing Well, by William Zinsser (Amazon link)
• Style: The Basics of Clarity and Grace, by Joseph Williams and Gregory Colomb (Amazon link)
• Common Errors in English
• English Grammar FAQ (alt.usage.english)
• Bob's quick guide to the apostrophe, you idiots (funny)
• Merriam-Webster's Concise Dictionary of English Usage (Amazon link): Scholarly but user-friendly, evidence-based advice; very good for non-native speakers, especially for preposition usage.
• English Language and Usage StackExchange: Question and answer site for English language usage.