この記事は翻訳作業中です。

整理され、標準化され、読みやすい書き方でドキュメンテーションを示すために、Mozilla Developer Netework スタイルガイドはテキストがどのような体系、表記、書式などに従うべきなのかを説明します。これらは厳密な規則というのではなくガイドラインです。形式よりも内容が重要であり、このため貢献する前にガイドラインを学ばなければならないと重荷に感じたりしないでください。とはいえ、真面目な他のボランティアが、あとであなたの成果をガイドラインに添うように書き換えても、びくびくしたり、ぎょっとしたりもしないでください。

このガイドにおける言語的な観点は主に英語のドキュメンテーションに向けられたものです。その他の言語については独自のスタイルガイドを持っているかもしれません(是非つくってください)。そのページはローカリゼーションについての記事のサブページとして作成されるべきです。

2017年12月現在、日本語独自コンテンツとしてのスタイルガイドは未作成だが、下記の資料が参考になります。

MDN 以外のサイトの記事での標準的なスタイルを知りたければ、One Mozilla style guideを参照してください。

基本事項

一般的なスタイルガイドのやり方に習って、とても基本的な文章上の取り決めから始めて、ドキュメンテーションを首尾一貫したものにしましょう。以下のセクションでは、その基本のアウトラインを示します。

ページタイトル

ページタイトルは検索結果に利用されます。またページ上部でページ間の階層構造を示すパンくずリストのために利用されます。ページタイトルは(ページのトップと検索結果に表示され)ページの「スラッグ」とは違っていても構いません。「スラッグ」とは、ページの URL の "<locale>/docs/" に続いている部分のことです。

タイトルと見出しの大文字化

ページタイトルセクションの見出しはセンテンススタイルの大文字化 (文頭と固有名詞の初めの1字だけを大文字にします) を用いるべきです。一般的なヘッドライン スタイルは用いません。

  • 正しい: "A new method for creating JavaScript rollovers"
  • 間違い: "A New Method for Creating JavaScript Rollovers"

この表記法が確立するより前の古い記事が多くあります。必要により気軽に書き換えてください。だんだん新しいやり方に慣れていくでしょう。

タイトルとスラッグの決め方

ページのスラッグは短くするべきです。つまり新しい階層を作るとき、スラッグは1つか2つの単語で構成されるようにしましょう。

一方で、タイトルは常識的な範囲で好きなだけ長くして構いません。また記事の内容がよくわかるものであるべきです。

サブツリーの新規作成

あるトピックとその周辺についていくつかの記事を追加する必要があるとき、ふつうはランディングページを作ってから書く記事をサブページとして追加します。ランディングページは1つか2つのパラグラフで、トピックやテクノロジーについての説明をします。つぎにそれぞれのページについて説明するサブページ一覧を付け加えます。我々が用意したマクロを利用すれば、一覧にページを追加する作業を自動化できます。

例えば、JavaScript ガイド を見てみましょう。以下のような構造になっています。

階層の最上位部に自分の記事を配置しないようにしましょう。サイトのパフォーマンスを下げ、検索とサイト探索を非効率にします。

General article content guidelines

When writing any document, it's important to know how much to say. If you ramble on too long, the article becomes tedious to read and nobody will use it. Getting the amount of coverage right is important for several reasons. Among those reasons: to ensure that the reader finds the information they truly need, and to 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 a little 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 on too long about it all. We have a few 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. An 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 code, for instance.

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 reader to understand if the article is likely to be covering what they're interested in reading about. In 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 technology, technologies, and/or APIs that are being documented or discussed, with links to those, and it should offer hints as to the situations in which the article's contents might be useful.

あまりにも短い例

この要約の例は、あまりにも短すぎます。"stroke"Textについてや、テキストが描画される場所や、正確に何を意味するのかなど、あまりにも多くの情報を除外しています。

CanvasRenderingContext2D.strokeText()は、文字列を描画します。

Example: Too long!

Here, we've updated the summary, but now it's far too long. Too much detail is included, and the text gets far too much into other methods and properties. Instead, the summary should focus on the strokeText() method, and should refer to the appropriate guide where the other details are offered.

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

More pages should have examples than should not have them. The majority of pages most likely deserve multiple examples, in fact. 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.

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.

In addition, 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 feature anything directly 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 that can't reasonably be expanded, but treat this guideline as a minimum target length when possible.

セクション、段落、改行

降順に見出しレベルを使い分けてください。 <h2>, <h3>, <h4> という順に、途中を飛ばさず使って下さい。H2 が最高の見出しレベルなのは H1 はページタイトルのために用意されているからです。H3 、H4 より深いレベルの見出しが必要になったときは、小さい記事に分割し、ランディングページにまとめてNext, Previous, PreviousNext マクロでリンクすることを考慮してみてください。

見出しで行うことと行ってはいけないこと

  • 単独のサブセクションを作らないでください。トピックを一つに分割するというのは意味のわからないことです。2つ以上のサブ見出しを用意するか、まったくないかのどちらかです。
  • 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, with the exception of certain macros designed specifically 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.

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.

Lists

Lists should be formatted and structured uniformly across all contributions. Individual list items should be written with suitable punctuation, regardless of the list format. However, depending on the type of 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. Periods 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, close off the numbered list with a brief summary or explanation of 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 item per number or step.

テキストの書式とスタイル

"Formatting Styles" ドロップダウンリストを使ってあらかじめ設定されたスタイルを選択範囲に適用してください。

注記: "注記" は重要な注意を呼びかけるのに使われます。こんな感じです。
警告:同様に、"警告" は警告ボックスをこのように作成します。

特別にそのように指示されたのでない限りは、HTML style 属性を手作業で付加しないようにしてください。既存のクラスでうまくいかなければ、#mdn で質問してみてください。

コードサンプルのスタイルと書式

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.

タブと改行

タブはスペース2つで統一して下さい。コードは綺麗にインデントされているべきです。始めの中括弧("{")は行頭に置きません。ブロック宣言の直後に配置します。

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 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);

インライン コードの書式

"コード"ボタン("<>"という山括弧記号が付いています)を使ってください。インライン コード スタイルの書式を関数名、変数名、メソッド名に適用することができます(これには、<code> 要素が使われています)。例えば、"frenchText() 関数"。

メソッド名の後には括弧をつけるべきです: doSomethingUseful() のように。括弧があることでメソッドとその他のコードの用語を区別できます。

構文の強調表示

Screenshot of the 'Syntax Highlighter' menu.コード行全体(もしくは数行のコード)は構文の強調表示によってフォーマットされるのが好ましく、<code>要素は使われるべきではありません。ツールバーの"pre"ボタンをクリックしてください。書式設定されたコンテンツボックスが挿入されます。そこにコードを入力しましょう。それからテキスト入力カーソルをコンテンツボックス内に置いたまま、右図のように"pre"ボタンの右にあるリストボタンから適切な言語を選択しましょう。以下の例は JavaScript の書式です。

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, and nesting these breaks certain aspects of our styling.

The following example shows text with JavaScript formatting:

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

探している言語が見当たらなければ、言語を指定せずに pre タグを利用して下さい(リストの"No Highlight"を選びます)。

x = 42;

構文の定義

シンタックスの定義を挿入する場合には、エディタのツールバーの"Styles"ドロップダウンメニューから、"Syntax Box"オプションを選択することができます。これより、シンタックスの定義で、通常のコードと区別する特別な書式を与えることができます。

Blocks not referring to code

There are a few 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 class. Those cases include things like 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.

HTML 要素に言及する際のスタイル

HTML 要素について記述する際に従うべき特定の規則があります。これらの規則によって、要素とその構成部分についての説明に一貫性が生まれます。また、詳細な説明への適切なリンクを保証することもできます。

要素名
HTMLElement マクロを使ってその要素のページへのリンクを生成します。例えば {{HTMLElement("title")}} と書けば、 "<title>" と出力されます。リンクを生成したくなければ、名前を山括弧に入れて "Inline Code" スタイルを使用してください (例えば <title>)。
属性名
"Inline Code" スタイルを使用して属性名をコードフォントに入れてください。加えて、属性が何をするのかの説明に関連して言及された場合、または文書中で最初に使用された場合は 太字フォント を使用してください。
属性の定義
属性名の定義には htmlattrdef マクロを使用してください (例えば、{{htmlattrdef("type")}})。そうすれば他のページから属性の定義を参照するために、 htmlattrxref マクロを使用するだけで簡単にリンクすることができます (例えば {{htmlattrxref("attr","element")}}
属性値
属性値に <code> を適用するために "Inline Code" スタイルを使用し、文字列の値はコード例の構文で必要がない限り、引用符で囲まないでください。例: 「<input> 要素の type 属性が email または tel に設定されている場合...」

ラテン文字の略記

注釈と括弧内で

  • よく使われるラテン語の略記(etc.、i.e.、e.g.)は括弧や注釈の中で使用できます。略記にはピリオドを使用してください。
    • 正しい: Web browsers (e.g. Firefox) can be used ...
    • 間違い: Web browsers e.g. Firefox can be used ...
    • 間違い: Web browsers, e.g. Firefox, can be used ...
    • 間違い: Web browsers, (eg: Firefox) can be used ...

通常の文で

  • 通常の文では(つまり注釈や括弧の外で)、英語における同等の表現を使用してください。
    • 正しい: ... web browsers, and so on.
    • 間違い: ... web browsers, etc.
    • 正しい: Web browsers such as Firefox can be used ...
    • 間違い: Web browsers e.g. Firefox can be used ...

ラテン語の略記表現と対応する英語表現

略記 ラテン語 英語
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

注記: ラテン語の略記表現が有用かどうか常に考えるようにしましょう。めったに使われないようなものは、多くの読者にとっては理解できず、他のものと勘違いしてしまうこともありえます。使用するあなたが正しく使用することを肝に銘じてください。例えば、"e.g."と"i.e."の取り違えはよくある間違いです。

頭字語と略語

大文字とピリオド

頭字語と略語において、全て大文字とし、ピリオドは使用しないでください。組織の略称もこれに含まれます。"US"や"UN"などです。

  • 正しい: XUL
  • 間違い: X.U.L.; Xul

略語の展開

ある用語についてページ内で初めて言及がある場合は、ユーザにとって馴染みがないと思われる略語を展開しましょう。よく分からなければ、展開するかもしくは記事や、用語の説明をする glossary の項目へのリンクを貼りましょう。

  • 正しい: "XUL (XML User Interface Language) is Mozilla's XML-based language..."
  • 間違い: "XUL is Mozilla's XML-based language..."

頭字語と略語の複数形

頭字語と略語の複数形については、s を末尾に付加するだけにしてください。アポストロフィは使用しないでください。絶対に。お願いします。

  • 正しい: CD-ROMs
  • 間違い: CD-ROM's

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

The contraction "vs." is preferred.

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

大文字の使用

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 if you wish to abbreviate the name of the "Escape" key, you may use "ESC".

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 the rules of the language in which the code is written mandate 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)

短縮形

書体はカジュアルで構いません。なので気軽に短縮形を使ってください(例えば、"don't"、"can't"、"shouldn't")。無理にとは言いません。

複数形

英語におけるやり方にしてください。ラテン語やギリシア語に影響を受けた形は使わないでください。

  • 正しい: syllabuses, octopuses
  • 間違い: syllabi, octopi

ハイフンを用いた複合語

接頭辞と後に続く語間で同じ母音が連続する場合にハイフンを使用してください。

  • 正しい: email, re-elect, co-op
  • 間違い: e-mail, reelect, coop

中性的な表現

性別が主題でない記事を書くときには、中性的な表現を使用することは良いことです。記事はできるだけ排他的でない方がいいでしょう。例えばある特定の男性("man")の行動について話題にするとき、彼が・彼の("he/his)と書くのはいいことですが、両性について言えることなら、彼が・彼の("he/his")というのは不適切です。

以下に例をあげましょう。

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.

どちらも性的に偏りがある表現です。中性的な代名詞に修正しましょう:

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

注記: MDN では、とても一般的な文法 (それは使用法の権威の議論対象です) を使うのを許可されており、これは英語で中性がないのを穴埋めするためのものです。三人称複数型を中性名詞として使う (つまり、"they"、"them"、"their"、"theirs"を使う) ことは許容されるやり方で、一般には "singular 'they'" として知られています。

両方の性についての記述することもできます:

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

ユーザを複数とするとこうなります:

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

もちろん一番良い解決法は、代名詞を使用しないよう書き直すことです:

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.

最後の手段がおそらく、より良い手段と言えるでしょう。文法的な正確さが十分でなくなるだけで、言語によっては大きく異なるジェンダールールに対応することに関する複雑性がなくなります。純粋な読み手にとっても、ローカリゼーションに参加する協力者たちにとっても、結果的に翻訳が容易になります。

数字と数詞

日付

日付については(コード中の日付は関係ありません)、"January 1, 1990"のようなフォーマットを使用してください。

  • 正しい: February 24, 2006
  • 間違い: February 24th, 2006; 24 February, 2006; 24/02/2006

YYYY/MM/DD フォーマットを使っても構いません。

  • 正しい: 2006/02/24
  • 間違い: 02/24/2006; 24/02/2006; 02/24/06

年代の表現

年代の表現には、"1990s" フォーマットを使って下さい。アポストロフィはいりません。

  • 正しい: 1990s
  • 間違い: 1990's

数詞の複数形

数詞の複数形には"s"を付加してください。アポストロフィはいりません。

  • 正しい: 486s
  • 間違い: 486's

カンマ

通常の文では、5桁以上の数字にだけカンマを使用してください。

  • 正しい: 4000; 54,000
  • 間違い: 4,000; 54000

句読点

Serial Comma(連続のカンマ)

Serial comma(連続のカンマ)を使用してください。 Serial Comma または "Oxford" comma(オックスフォードカンマ)としても知られるこのカンマは、3つ以上の文を並列する際に接続詞の直前に置きます。

  • 正しい: I will travel on trains, planes, and automobiles.
  • 間違い: I will travel on trains, planes and automobiles.

注記: これは One Mozilla style guide のやり方とは対対照的です。Serial Comma (連続のカンマ)は使われないと明記しています。MDN のやり方はこのルールの例外です。

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. First, because we need to choose one or the other for consistency, and second, because if curly quotes or apostrophes make their way into code snippets (even inline ones), readers may copy and paste them and expect them to function, which they will not.

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

綴りの統一

ゆれのあるスペルについては  Dictionary.com で最上位にくるエントリを使用して下さい。他のものは使用しないでください。

  • 正しい: localize, behavior
  • 間違い: localise, behaviour

用語集

HTML 要素

「要素」は HTML と XML の要素を表し、「タグ」ではありません。加えて、よそは常に「<>」で囲んで記述し、 <code> の中に入れてください。その要素を節の中で初めて参照するときは、 HTMLElement マクロを使用して要素の文書へのリンクを作成してください (その要素のリファレンス文書ページ内で書いている場合を除く)。

  • 正しい: the <span> element
  • 間違い: the span tag

Parameters vs. arguments

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

ユーザインターフェイス

一連の作業を記述する際には、命令調でインターフェイスでの操作を指示しましょう。ユーザインターフェイスの要素をラベルとタイプではっきりと指定しましょう。

  • 正しい: Click the Edit button.
  • 間違い: Click Edit.

能動態と受動態/h3>

能動態が一般的には好ましいですが、MDN の堅苦しくない雰囲気から考えると受動態も問題ありません。けれど、どちらか首尾一貫させる意識は必要です。

Wiki のマークアップとその用法

リンク

wikiが協力な学習・教育ツールとなるのに、大半はリンクのおかげです。以下にいくつかの基本情報がありますが、完全なガイドは編集ガイド内の MDNでリンクを作成・編集する で見る事ができます。

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.
  • For a term for which you're linking to a page defining or discussing that term, use the name of the term and no additional text as the link's text. 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:

URL スキーム

セキュリティの理由から、下記のスキームを使用したリンクだけを作成すべきです:

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

これ以外は動作したりしなかったりしますが、サポートされません。おそらく編集スタッフによって削除されるでしょう。

特に、 about:chrome:// スキームは、動作しないので使用しないよう注意してください。同様に javascript: スキームはたいていのモダンブラウザからブロックされ、jar: も同様です。

ページタグ

タグはページについてのメタ情報を提示するか、内容に改善すべき点があるということを示します。あるいはその両方です。Wiki のどのページもタグづけされる必要があります。タグ付けのやり方については適切にタグづけする方法のガイドに詳しいです。

タグのインターフェイスは編集モードにおいて、ページ下部で機能しています。以下のような感じです。

Screenshot of the UX for adding and removing tags on MDN

タグを追加するには、タグリスト末尾の編集ボックスをクリックしてタグ名を入力します。タグには補完機能があります。Enter (かreturn) キーで新規タグを投稿できます。どの記事も必要なだけタグを追加してよいです。例えば、AJAX プログラミングにおける JavaScript の記事には "JavaScript" と "AJAX" のどちらのタグも必要でしょう。

タグを削除するには、タグアイコンの "X" をクリックしてください。

手を加える必要がある記事にタグをつける

記事の品質と内容についての情報を示すためだけでなく、ある種の作業が必要な記事にもタグをつけることがあります。

古くなったページにタグをつける

現状に即していない記事には以下のタグをつけてください。

  • Junk: スパム記事、誤って作られたページ、見る価値の無い劣悪なページにはこのタグをつけて下さい。このタグがつけられたページは定期的に削除されます。
  • Obsolete: 技術的に既に古いが、ある文脈上では使用されうることについての記事にはこのタグをつけて下さい。例えば、HTML5 では時代遅れな HTML 要素も HTML 4.01 ではまだ有効です。そのトピックについて obsolete_header マクロを使って目印をつけることができます。
  • Archive: 技術的に既に古く、最早役に立たないものにはこのタグをつけてください。できれば、読者にもっと新しい記事を読むように促す注記をつけてください。例えば、 Mozilla CVS リポジトリをどのように使うかについての記事は Mercurial リポジトリについての新しい記事に読者を誘導するべきでしょう(対応する記事が存在しなければ、NeedsUpdate タグをつけてください。そして Talk ページに説明を加えて下さい)。Archive タグのつけられた記事はそのうち、MDN の主要部分から Archive セクションへと移されます。

SEO summary

SEO summary は簡潔なページの概要です。サイトを巡回するプログラムに記事の概要として渡され、ページの検索結果として表示されます。MDN のランディングページの作成を自動化するマクロにも利用されます。

デフォルトでは、ページ最初の段落が SEO summary として利用されます。しかし、WYSIWYGエディタ内の "SEO summary" スタイルを利用してセクションをマークすることで上書きすることができます。

ランディングページ

ランディングページ はサイトにおける、ある分野の起点となるページです。例えば CSSHTML のメインページです。下記の3エリアからなる標準的なフォーマットがあります。

  1. その技術がどういうもので、どのように使用されるかについての簡潔な(大抵はひとつのパラグラフからなる)概観。詳しくは Writing a landing page overview を参照してください。
  2. 適切に見出しがつけられた、2段組のリンクリスト。Creating a page link list のガイドラインを参照してください。
  3. ページ最下部の "ブラウザの互換性" は任意です。

ページリンクリストの作成

MDN ランディングページのリンクリストセクションは2段組からなります。下記の HTML コードによって生成されます。

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

左の段は記事のリストになります。上部の <h2> ヘッダはとあるトピック(例えば、"Documentation and tutorials about foo")についての記事のリストであることを説明します。つまり、このヘッダは CSS の "Documentation" クラスを使用するべきです。その下には、記事の <dl> リストが続きます。リストには各記事へリンクした <dt> ブロックと、1行から2行程度の記事の概要に対応した <dd> ブロックがあります。

右の段は以下のセクションをひとつ以上含む必要があります。順に、

コミュニティの協力を得る
このセクションは IRC チャンネルと、トピックについて役に立つメーリングリストの情報を提供します。見出しは "Community" クラスを利用するべきです。
ツール
このMDNセクションに記述された技術を使う時に、ユーザの助けになるツールの一覧です。見出しは "Tools" クラスを利用するべきです。
関係するトピック
その他の、関係する技術についてのランディングページへのリンクリストです。見出しは "Related_Topics" クラスを利用するべきです。

<<<finish this once we finalize the landing page standards>>>

イメージの利用と挿入

作成、編集している記事にイメージを挿入することは時々役に立ちます。特に記事が高度に技術的である場合です。イメージを利用するには、

  1. 適切なイメージファイルを記事に添付しましょう(編集モードで記事の最下部にてできます)。
  2. WYSIWYG エディタでイメージを作成します。
  3. WYSIWIG エディタの添付ファイルのドロップダウンリストから、新規作成した、あなたのイメージの添付ファイルを選択します。
  4. OK を押してください。

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

その他のリファレンス

おすすめのスタイルガイド

ここで取り扱われていない用法とスタイルについて疑問があれば、Economist style guide を、それでもダメなら Chicago Manual of Style を参照してください。

おすすめの辞書

単語の綴りにわからないことがあれば、 Dictionary.com を参照してください。このサイトのスペルチェッカはアメリカ英語を基準にしています。それ以外の表記を使用しないでください(例えば colour でなく color です)。

何度もガイドが拡張されることになるでしょう、ですからこのドキュメントで取り扱われていないことについて知りたければ、その質問を MDC mailing listproject lead に送ってください。MDNの協力者が追加すべき記事を知ることができます。

MDN 独自の内容について

言語、文法、綴り

記事の執筆と編集スキルを磨きたければ、以下のリソースが役立つことでしょう。(英語の情報)

ドキュメントのタグと貢献者

最終更新者: mfuji09,