執筆スタイルガイド

この執筆スタイルガイドは、MDN Web Docs でコンテンツをどのように書き、整理し、綴り、形式を整えるべきかを記述したものです。

これらのガイドラインは、ウェブサイト全体の言語とスタイルの一貫性を確保するためのものです。とはいえ、私たちは形式よりも内容に関心を持っていますので、投稿する前に執筆スタイルガイドをすべて学ぶ必要はないと思ってください。ただし、後で他の投稿者があなたの作業をこのガイドに適合するように編集した場合でも、怒ったり驚いたりしないでください。また、あなたがコンテンツのプルリクエストを提出する際に、レビュアーがこのスタイルガイドを指し示すかもしれません。

メモ: このガイドの言語的な側面は、主に英語の文書に適用されます。他の言語では、独自のスタイルガイドがあるかもしれません（作成することも歓迎されます）。これらは、それぞれのローカライズチームのページのサブページとして公開すべきです。しかし、このガイドは、コンテンツの形式や構成に関しても参照されるべきです。

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

一般的なガイドラインを記載した後、このガイドでは MDN Web Docs で推奨される書き方、そしてリストやタイトルなど、ページ上のさまざまな構成要素をどのようにフォーマットするかについて説明します。

全般的な執筆ガイドライン

目標は、読者がそのトピックを理解するために必要なすべての情報を載せたページを書くことです。

以下の項では、そのための推奨事項を示します。

ターゲット層を考慮する

書こうとしているコンテンツの対象読者を念頭に置いてください。例えば、高度なネットワーク技術に関するページでは、ネットワークの基本的な概念について、一般的なネットワークに関するページほど詳しく説明する必要はないでしょう。これらはあくまでガイドラインであることを念頭に置いてください。これらのヒントの中には、すべてのケースに適用されないものもあります。

執筆において 3 つの C を意識する

良い文章を書くための 3 つの C とは、明確に (clearly)、簡潔に (concisely)、一貫性を持って (consistently) 書くことです。

  • 明確に: 文章が明確でシンプルであることを確認してください。一般に、能動態とあいまいでない代名詞を使用してください。短い文章を書き、一文につき一つの考えにとどめましょう。新しい用語は、使用する前に対象読者を想定して定義しましょう。
  • 簡潔に: どのような文書化でも、どの程度語るかということが重要です。過剰に詳細を提供すると、このページは読むのが面倒になり、ほとんど使用されなくなります。
  • 一貫性: ページ全体で、また複数のページにわたって、一貫して同じ文言を使用するようにしましょう。

関連する例を載せる

一般的に、書いている内容をよりよく説明するために、例や実際のシナリオを追加します。これにより、読者は概念的・手続き的な情報を、より具体的かつ実用的な方法で理解することができます。

例を使用して、すべての引数が何のために使用されるのかを明確にし、存在する可能性のある希少な例を明確にする必要があります。 また、一般的なタスクに対する解決策や、発生しうる問題に対する解決策を示すためにも、例を使用することができます。

説明的な導入文の提供

最初の見出しの前の段落で、このページで取り上げられる情報、そしておそらく読者がその内容を一通り読んだ後に達成できることを適切に要約するようにしましょう。こうすることで、読者はこのページが自分の関心事や望ましい学習成果に関連しているかどうかをすぐに判断することができます。

ガイドまたはチュートリアルでは、序文で、これから取り上げられるトピックと、読者が保有することが期待される前提知識について、読者に知らせる必要があります（もしあれば）。冒頭の段落では、文書化または議論されている技術や API、関連する情報へのリンクに言及し、記事の内容が使用されるかもしれない状況へのヒントを提供する必要があります。

  • 短い導入文の例 この紹介文の例はあまりにも短すぎます。例えば、テキストを「描画する」とはどういうことか、テキストはどこに描かれるのか、などなど、多くの情報が抜けています。

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

  • 長い導入文の例: この例は導入文を更新したものですが、今度は長すぎます。 あまりにも詳細な内容が含まれていて、他のメソッドやプロパティにテキストが入り込みすぎています。 要約は strokeText() メソッドに焦点を当て、他の詳細が提供されている適切なガイドを参照してください。

    Canvas 2D API の CanvasRenderingContext2D.strokeText() メソッドは呼び出されると、指定された座標から始まる指定された文字列内の文字を、現在のペンの色を使って輪郭を描きます。 コンピューターグラフィックの用語では、テキストを「ストロークする」とは、文字の内容を色で塗りつぶさずに、文字列内の字形の輪郭を描くことを意味します。

    テキストは、コンテキストの font プロパティで指定されたコンテキストの現在のフォントを使用して描画されます。

    指定された座標に対するテキストの相対的な配置は、コンテキストの textAlign, textBaseline, direction プロパティによって決定されます。 textAlign は、指定された X 座標に対する文字列の配置を制御します。値が "center" の場合、文字列は x - (stringWidth / 2) から始まり、文字列の中央に配置するように描画されます。 値が "left" の場合は、文字列は指定された X 座標から描画されます。 また、 textAlign が "right" の場合は、指定されたX座標で終わるように描画されます。

    (…)

    オプションで、4 番目の引数を指定して文字列の最大幅をピクセル単位で指定することもできます。 この引数を指定すると、テキストは水平方向に圧縮されるか、描画時にその幅の空間に収まるように拡大縮小 (あるいは調整) されます。

    fillText() メソッドを呼び出すことで、文字列の輪郭のみを描画するのではなく、文字列の文字を色で塗りつぶすことができます。

  • 適切な導入部の例: ここで、 strokeText() メソッドのより良い概要を見てみましょう。

    CanvasRenderingContext2D の strokeText() メソッドは、 Canvas 2D API の一部で、指定された文字列の文字の輪郭を、指定された X 座標と Y 座標で示された位置に描画します。 テキストは、コンテキストの現在の font を使用して描画され、 textAlign, textBaseline, direction の各プロパティに従って揃えられます。

    詳細とさらなる例については、図形の描画ページのテキストの節や、このテーマに関するメインの記事、テキストの描画を参照してください。

差別的でない言葉

MDN は幅広く、多様な読者を抱えています。 私たちは、可能な限り差別的でないテキストを維持することを強く推奨します。 ここでは、文書で使用される一般的な用語に代わるものをいくつか紹介します。

  • master （マスター）や slave （スレーブ）という用語を避け、 main （メイン）や replica （レプリカ）を使用してください。
  • whitelist （ホワイトリスト）や blacklist （ブラックリスト）を allowlist （許可リスト）や denylist （拒否リスト）に置き換えてください。
  • sanity （正気）は coherence （正常性）に置き換えてください。
  • dummy （ダミー）の代わりに placeholder （プレイスホルダー）を使用してください。
  • 文書で crazy や insane を使用する必要はありませんが、場合によっては fantastic （驚異的）を代わりに使用することを検討してください。

性別が主題と関係ない文章では、性別に関係ない言葉を使用するのが一番です。 例えば、特定の男性の行動について話している場合は、 "he"/"his" を使用しても問題ありませんが、主語がどちらでもありうる場合は、 "he"/"his" は適切ではありません。

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

  • 誤: "A confirmation dialog asks the user if he wants to allow the web page to make use of his webcam."
  • 誤: "A confirmation dialog asks the user if she wants to allow the web page to make use of her webcam."

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

  • 正: "A confirmation dialog asks the user if they want to allow the web page to make use of their webcam."

メモ: MDN Web Docs では、一般に「単数形の 'they'」として知られている、三人称複数型を中性名詞として使う（つまり、"they"、"them"、"their"、"theirs" を使う）ことを許容しています。

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

  • 正: "A confirmation dialog asks the users if they want to allow the web page to make use of their webcams."

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

  • 正: "A confirmation dialog requesting the user's permission for webcam access appears."
  • 正: "A confirmation dialog box that asks the user for permission to use the webcam appears."

最後の手段がおそらく、より良い手段と言えるでしょう。これは文法的に正しいだけでなく、性別の規則が大きく異なる可能性のある異なる言語間で、性別の取り扱いに関連した複雑さを軽減することができます。この解決策は、読者と翻訳者の両方にとって、翻訳をより簡単にすることができます。

SEO を意識して書く

MDN Web Docs で書くことの第一の目標は、常にオープンなウェブ技術について説明し、情報を提供することで、開発者がやりたいことを素早く習得したり、コードを完成させるために知っておくべき小さな詳細を見つけたりすることですが、私たちが書いた素材を開発者が発見できるようにすることも重要です。そのためには、検索エンジン最適化（SEO）を意識して書くとよいでしょう。

この章では、検索エンジンが私たちの素材を簡単に分類してインデックス化し、読者が必要なものに簡単に見つけられるようにするための、コンテンツに関する標準的な実践、推奨、要件について述べます。 SEO ガイドラインには、執筆者や編集者が作業する各ページが、検索エンジンが記事を適切にインデックスするために必要な文脈や手がかりを与えるよう、合理的に設計され、書かれ、マークアップされていることを確認することが含まれます。

このページと隣接するページが検索エンジンに適切にインデックスされるようにするために、コンテンツを書いたり見直したりする際に、次のようなチェックリストを念頭に置いておくとよいでしょう。

  • ページが似すぎていないことを確認する。このページのコンテンツがテキスト的に似ていると、検索エンジンは、たとえそうでなくても、そのページが同じことについて書かれているとみなしてしまいます。 例えば、あるインターフェイスに width と height というプロパティがある場合、この 2 つのプロパティを文書化した 2 つのページでは、いくつかの単語を入れ替えたり、同じ例を使用するだけで、驚くほど似たような文章になりがちです。これでは、検索エンジンはどちらがどちらかわからなくなり、ページランクを共有することになり、結果的にどちらも見つけるのが難しくなってしまいます。

    そこで、すべてのページが自身のコンテンツを保有することが重要です。ここでは、そのためのヒントをいくつかご紹介します。

    • より固有な概念を説明する。意外と違いがあるかもしれない使用例を考えてみます。例えば、 width と height のケースでは、水平方向の空間と垂直方向の空間がどのように異なる使い方をされているかを考え、適切な概念についての議論を行います。例えば、幅についてはサイドバーを設置するための空間として、高さについては縦方向のスクロールやフッターなどのために使用することを考えます。また、アクセシビリティの問題についての情報を盛り込むことも、有用かつ重要なアイデアです。
    • 異なる例を使用する。各ページにまったく異なる例を使ってください。このような場合の例は、本文よりもさらに似通っていることが多いものです。というのも、例はそもそも似たようなメソッドやプロパティの両方（またはすべて）を使用していることがあり、再利用する際に実質的な変更を必要としないからです。そのため、例を捨てて新しい例を書くか、少なくとも複数の例を用意し、そのうちのいくつかは異なる例文してください。
    • 例に説明文を追加する。それぞれの例について説明を加えてください。トピックの複雑さと対象読者を考慮して、適切なレベルの詳細で、例が何をするのかという概要と、どのように機能するのかという説明の両方を含める必要があります。

    同じような内容になりすぎないようにするには、時間が許す限り、それぞれの記事を一から書き直すのが一番簡単です。

  • このページが短すぎないようにする。ページの内容が小さすぎると（SEO 用語で「薄いページ」と呼ばれます）、検索エンジンは正確なカタログ化が困難です。短すぎるコンテンツページは探すのが大変です。 MDN Web Docs のページは、可能な限り 300 語前後よりも短くしないでください。人為的にページを膨らませるのではなく、可能な限りこのガイドラインを最小の目安となる長さとして扱ってください。

    このページでは、不要なテキストでごちゃごちゃさせることなく、適切に検索できるような十分なコンテンツを保有するページを作成するための基本的なガイドラインをご紹介します。

    • スタブを避ける。明らかに記事がスタブであったり、内容が不足している場合は、追加してください。 MDN Web Docs では、完全な「スタブ」ページは避けるようにしていますが、存在します。しかし、コンテンツの大部分が欠けているページはたくさんあります。

    • ページの構成を見なおす。ページがそのページの種類に応じて適切に構成されているか確認してください。すべての節が存在し、適切なコンテンツがあることを調べてください。

    • 完全性を確保する。すべての節が完全で、最新の情報が含まれていることを確認してください。すべての引数がリストアップされ、説明されているか。例外がカバーされていることを確認してください（これは特にコンテンツが欠けていることが多い場所です)。

    • すべての概念が完全に具体化されていることを確認する。すべての項目が詳細に説明されているかどうか。簡単な説明をするのは簡単ですが、すべてのニュアンスが含まれているかどうかを確認してください。特別なケースはありますか？読者が知っておくべき既知の制限はありますか？

    • 例を追加する。すべての引数、あるいは少なくとも初級から中級レベルのユーザーが使用する可能性のある引数（またはプロパティや属性）と、追加の説明が必要な高度な引数を網羅した例を用意する必要があります。それぞれの例の前には、その例が何をするのか、それを理解するためにはどのような知識が必要なのかなどの概要を示す必要があります。例の後（または例の一部の間）には、コードがどのように動作するかを説明する文章が必要です。例の詳細やエラー処理についても手を抜いてはいけません。読者は例をコピー＆ペーストして自分のプロジェクトで使用するでしょうから、そのコードが本番サイトで使用されることになるでしょう。より有用な情報は、サンプルコードのガイドラインを参照してください。

    • 使用例を説明する。説明されている機能について、特に一般的な使用例がある場合は、それについて話してください。一般的な開発上の問題を解決するために文書化された方法を読者が理解すると仮定するのではなく、実際にその利用例についての節を追加し、例とその例がどのように機能するかを説明するテキストを追加してください。

    • 画像情報を追加する。すべての画像や図に適切な alt テキストを入れてください。このテキストは、表などのキャプションと同様に重要です。スパイダーは画像をクロールすることができないため、 alt テキストによって、埋め込まれたメディアに含まれるコンテンツを検索エンジンのクローラーに伝えることができます。

      メモ: 検索エンジンのランキングを操作するために、キーワードを入れすぎたり、関係のないキーワードを使ったりすることは、良い慣習ではありません。このような行為は発見されやすく、罰せられる傾向にあります。 同様に、ページのサイズや検索順位を上げるために、反復的で役に立たない内容や、キーワードの塊を実際のページ内に追加するようなこともしないでください。これは、コンテンツの読みやすさと検索結果の両方に悪影響を及ぼします。

    • トピックの内容を重視する。特定のキーワードではなく、記事のトピックに沿ってコンテンツを書く方がはるかに良いことです。実際、多くの SEO 担当者は、記事の長さに応じて 5 ～ 100 種類のキーワード（ショートテール、ミディアムテール、ロングテール）をリストアップし、記事に含めるようにしています。そうすることで、表現が多様化し、繰り返しが少なくなります。

執筆スタイル

英語で文法的に正しい文章を書くこと以外に、 MDN Web Docs 全体でコンテンツの一貫性を保つために、以下のガイドラインに従うことをお勧めします。

略語と頭字語

略語とは、長い単語を短くしたもので、頭字語とは、フレーズの各単語の最初の文字を使用して作成された新しい単語です。この章では、略語と頭字語のガイドラインについて記述します。

  • 略語の展開: ある用語についてページ内で初めて言及する場合は、ユーザーにとって馴染みがないと思われる略語を展開しましょう。判断が付かない場合は、用語を展開してください。記事や、用語の説明をする用語集の項目へのリンクを貼りましょう。

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

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

    • 正: XUL
    • 誤: X.U.L.; Xul

  • ラテン語の略語: よく使われるラテン語の略語 (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." の取り違えはよくある間違いです。

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

    • 正: CD-ROMs
    • 誤: CD-ROM's

  • "Versus", "vs.", "v.": 短縮形を使用する場合、"vs." の方が "v." よりも望ましく、見出しに使用することができます。それ以外の本文中では、綴り字の形式である "versus" を使用し てください。

    • 正: this vs. that
    • 誤: this v. that
    • 誤: this versus that

大文字の使用

本文では標準的な英語の大文字表記ルールを使用し、 "World Wide Web" は大文字で表記してください。 "web" （単独または修飾語としての使用）および "internet" は小文字を使用してもかまいません。

メモ: このガイドラインは以前のバージョンからの変更であり、 MDN では "Web" と "Internet" がたくさん使われているのを見かけるかもしれません。 他の変更を行う際にこれらを変更するのは自由ですが、大文字小文字を変更するためだけにこの記事を編集する必要はありません。

キーボードのキーは、すべて大文字にするのではなく、文章形の大文字を使用してください。 例えば、 "Enter" であり "ENTER" ではありません。 唯一の例外として、 "ESC" を "Escape" キーの略語として使用することができます。

大文字を含む商標や人名に由来する単語など、特定の単語は常に大文字にする必要があります（ただし、その単語がコード内で使用され、コード構文が小文字を要求する場合を除きます）。 いくつかの例を挙げます。

  • Boolean（イギリスの数学者、論理学者 George Boole にちなんで命名されました）
  • JavaScript （オラクル社の商標です。常に商標として書く必要があります）
  • Python、TypeScript、Django などのプログラミング言語やフレームワークの名称

短縮形

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

数字と数詞

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

    • 正: 4000; 54,000
    • 誤: 4,000; 54000

  • 日付: 日付については（コード中の日付は関係ありません）、 "January 1, 1990" のような形を使用してください。

    • 正: February 24, 1906
    • 誤: February 24th, 1906; 24 February, 1906; 24/02/1906

    YYYY/MM/DD の形を使っても構いません。

    • 正: 1906/02/24
    • 誤: 02/24/1906; 24/02/1906; 02/24/06

  • 年代: "1990s" の形を使って下さい。アポストロフィは使わないでください。

    • 正: 1920s
    • 誤: 1920's

  • 数詞の複数形: "s" を付加してください。アポストロフィは使わないでください。

    • 正: 486s
    • 誤: 486's

複数形

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

  • 正: syllabuses, octopuses
  • 誤: syllabi, octopi

アポストロフィと疑問符

「曲がった」引用符と疑問符を使用しないでください。 MDN では、直線の引用符とアポストロフィのみを使用してください。これは、一貫性のために一方を選択しなければならないからです。曲がった引用符やアポストロフィがコードスニペットの中に入ってくると、インラインのものであっても、読み手はそれらをコピーして貼り付け、動作することを期待してしまうかもしれません（動作しないでしょう）。

  • 正: Please don't use "curly quotes."
  • 誤: Please don’t use “curly quotes.”

カンマ

以下の一覧は、カンマの使用規則に注意する必要がある一般的な状況を説明しています。

  • 導入節の後: 導入節は従属節で、通常、文頭に現れます。導入節の後にカンマを使用し、次の独立節と区切ってください。

    • 例 1:
      • 正: "In this example, you will see how to use a comma."
      • 誤: "In this example you will see how to use a comma."
    • 例 2:
      • 正: "If you are looking for guidelines, you have come to the right place."
      • 誤: "If you are looking for guidelines you have come to the right place."
    • 例 3:
      • 正: "On mobile platforms, you tend to get a numeric keypad for entering data."
      • 誤: "On mobile platforms you tend to get a numeric keypad for entering data."

  • 接続詞の前: シリアルカンマ（「オックスフォードカンマ」とも呼ばれる）は、 3 つ以上の項目が連続する場合に、接続詞の前に現れるカンマのことです。MDN Web Docs では、シリアルカンマを使用してください。また、リストの各項目はカンマで区切ってください。

    • 正: "I will travel on trains, planes, and automobiles."
    • 誤: "I will travel on trains, planes and automobiles."

    項目が 2 つだけのリストでは、 "and" と "or" の前にカンマを使用しないでください。

    • 正: "My dog is cute and smart."
    • 誤: "My dog is cute, and smart."

    接続詞 "and", "but", "or" が独立した 2 つの節をつなぐ場合は、その前にカンマを使用してください。ただし、接続詞によって文が非常に長くなったり、複雑になったりする場合は、 2 つの文として書き直すことを検討してください。

    • 例 1:
      • 正: "You can perform this step, but you need to pay attention to the file setting."
      • 誤: "You can perform this step but you need to pay attention to the file setting."
    • 例 2:
      • 正: "My father is strict but loving."
      • 誤: "My father is strict, but loving."

  • "that" と "which" の前: 制限節は文の意味にとって不可欠であり、残りの文から設定するためのカンマは必要ありません。制限節は通常 that で始まり、カンマを入れる必要はありません。

    • 正: "We have put together a course that includes all the essential information you need to work towards your goal."
    • 誤: "We have put together a course, that includes all the essential information you need to work towards your goal."

    非制限節は追加情報を提供するもので、文の意味にとって不可欠なものではありません。非制限節は通常 which で始まり、その前にカンマが必要です。

    • 正: "You write a policy, which is an allowed list of origins for each feature."
    • 誤: "You write a policy which is an allowed list of origins for each feature."

  • "such as" の前: "such as" が非制限節の一部で、残りの文が独立節の場合、"such as" の前にカンマを使用してください。

    • 正: "The Array object has methods for manipulating arrays in various ways, such as joining, reversing, and sorting them."
    • 誤: "The Array object has methods for manipulating arrays in various ways such as joining, reversing, and sorting them."

    以下の例では、"such as" にカンマを使用しない場合について説明しています。ここでは、"such as" を含む節が文の意味にとって不可欠となっています。

    • 正: "Web applications are becoming more powerful by adding features such as audio and video manipulation and allowing access to raw data using WebSockets."
    • 誤: "Web applications are becoming more powerful by adding features, such as audio and video manipulation, and allowing access to raw data using WebSockets."

ハイフン

ハイフンを使った複合語は、接頭辞の最後の文字が母音で、かつルートの最初の文字と同じ場合に使用してください。

  • 正: re-elect, co-op, email
  • 誤: reelect, coop, e-mail

綴り

アメリカ英語の綴りを使用してください。

一般的には、 Dictionary.com の最初の項目を使用しますが、その項目が変種の綴りとして記載されていたり、主にアメリカ以外の英語の形で使用されている場合を除きます。 例えば、 "behavior" を検索すると、 "Chiefly British" という言葉の後に、アメリカの標準形である "behavior" へのリンクが表示されます。変形スペルは使わないようにしましょう。

  • 正: localize, behavior, color
  • 誤: localise, behaviour, colour

用語

以下は、特定の専門用語を使用する際の推奨事項です。

  • HTML 要素: HTML や XML の要素を参照する場合は、「タグ」ではなく「要素」という用語を使用してください。さらに、要素は角括弧 "<>" で囲み、逆引用符 ( `) を使用してスタイル設定してください。例えば、逆引用符の中で <input> を使用すると、期待通りの <input> としてスタイル設定されます。

    • 正: <span> 要素
    • 語: span タグ

    MDN では、 HTML 要素を示すのに HTMLElement マクロを使うこともできます。これは、要素のスタイル設定、角括弧 "<>"、参照ページへのリンクを追加します。

    • 逆引用符の使用: <span>
    • マクロの使用: <span> （Markdown 内のソース: {{HTMLElement("span")}}）

  • parameter と argument: MDN で推奨する用語は parameter です。一貫性のためにできるだけ "argument" の用語は使用しないでください。

  • ユーザーインターフェイス操作: 一連の作業を記述する際には、命令調でインターフェイスでの操作を指示してください。ユーザーインターフェイスの要素をラベルと種類ではっきりと指定してください。

    • 正: "Click the Edit button."
    • 誤: "Click Edit."

能動態と受動態

能動態が一般的には好ましいですが、MDN の堅苦しくない雰囲気から考えると受動態も問題ありません。 ただし、整合を取るようにしてください。

ページの構成要素

この節では、見出し、メモ、リンク、例など、各ページのさまざまな部分に従うべきガイドラインを示します。

サンプルコード

MDN Web Docs のページには、1 つ以上のサンプルコードを含めることができます。MDN Web Docs のサンプルコードを書く際に、以下の一覧にあるようなことを推奨します。

  • それぞれのサンプルコードには、以下を載せてください。
    • 見出し: サンプルコードで示されるシナリオを記述するための短い ### (<H3>) の見出し。例：「オフセット印刷の使用」、「前のレイヤーのスタイルに戻す」。
    • 説明: サンプルコードの前に、読者の注意を喚起するために例の仕様を記述する短い説明文。例えば、「以下の例では、CSS で base と special という 2 つのカスケードレイヤーが定義されています。」
    • 結果の説明: サンプルコードの後に、結果やこのサンプルコードがどのように動作するかを記述する説明。
  • 一般的に、サンプルコードはその機能の構文や使用方法を示すだけでなく、ウェブ開発者がその機能を使用したい、または使用する必要があるような目的や状況に光を当てる必要があります。
  • 大きなサンプルコードを作成している場合、それを小さな論理的な部分に分割して、個別に記述できるようにすることが理にかなっている場合があります。
  • ライブサンプルを追加する際、サンプルを含む領域の <pre> ブロックは、サンプルを実行する前にすべて連結されることを知っておくと役に立ちます。 HTML、CSS、JavaScript の一部または全部を複数の部分に分割し、それぞれに説明や見出しなどを任意に設定することができます。これにより、コードの文書化が非常に強力かつ柔軟になります。

MDN Web Docs のサンプルコードをどのようにスタイルまたは整形するかについては、サンプルコードのスタイル設定のガイドラインを参照してください。

相互参照（リンク）

MDN で他のページやページの節のタイトルで参照する場合、リンクテキストでは文章の大文字小文字表記に従ってください（ページや節ののタイトルと同じです）。リンク先のページタイトルや節のタイトルと異なっていても、リンクテキストでは文章の大文字小文字表記を使用してください（ページタイトルや節タイトルで使用している大文字小文字表記が間違っている可能性があります）。リンクテキストに引用符を使用しないでください。 MDN でページをタイトルで参照するには、以下のスタイル設定を使用してください。

次のように、ページの節にリンクする場合も同様のスタイル設定を行ってください。

リンク先の節が同じページにある場合は、「上記」 (above) や「下記」 (below) の言葉を用いて、その節の場所を示唆することができます。

文章の一部を記事や記事の節にリンクすることができます。リンクテキストとして説明的な語句を使用し、リンクされているページに十分なコンテキストを提供するように注意してください。

MDN で、リファレンスページにリンクするもう一つの方法はマクロを使用することです。これらのマクロはよく使われるマクロページに記述されています。例えば、 HTML 要素のリファレンスページにリンクするには HTMLElement マクロを使用し、 CSS プロパティのリファレンスページにリンクするには CSSxRef マクロを使用します。

リファレンスページ、用語集ページ、ガイドの終わりにある関連情報の節でも、同様の相互参照ガイドラインに従っています。

外部リンク

MDN Web Docs では、特定の状況下において外部リンクを許可しています。MDN Web Docs で外部リンクを載せてよいかどうか判断するには、この節で記述されているガイドラインを使用してください。外部リンクを追加するためのプルリクエストは、ここで記述するガイドラインを満たしていない場合、拒否されます。

一般的に、外部リンクを追加することを検討している場合、以下のようなリスクが最小限であることを確認する必要があります。

  • リンク切れまたは古くなったリンク
  • 推奨しているように見えること（特に商用製品またはサービスについて）
  • MDN Web Docs を使用してスパムを広めようとすること。
  • リンクの宛先を難読化するショートリンク

メモ: 外部リンクを追加する前に、MDN Web Docs 内のコンテンツを相互参照することを検討してください。内部リンクはメンテナンスが簡単で、MDN Web Docs の全体が読者にとってより価値のあるものになります。

  • 良質な外部リンク: 良い外部リンクは、関連性があり、持続性があり、広く信頼されているリソースに読者を連れて行きます。以下のような外部コンテンツへのリンクを設定することをお勧めします。

    • 固有の、または不可欠なもの（例: IETF の RFC など）
    • 帰属表示、引用、謝辞のために必要なもの（例: クリエイティブ・コモンズの帰属表示の一部など）
    • MDN Web Docs 自体にそのようなコンテンツを組み込むよりも、トピックのために保守される可能性が高い（例: ベンダーのリリースノート）
    • MDN Web Docs 自体のように、オープンソースまたはコミュニティ主導であること。

  • 不適切な外部リンク: 関連性、保守性、アクセシビリティに欠け、読者にとって障害となるようなリンクは避けましょう。以下のような外部コンテンツへのリンクは避けてください。

    • 一般的なもの、固有性がないもの（例: 関連文書ではなく、ベンダーのホームページなど）
    • 一時的なもの、またはメンテナンスされていないもの（例: 一度限りのお知らせなど）
    • 自分へのリンクまたは自己宣伝（例: MDN Web Docs から作者自身の作品を削除した場合）
    • 有料（例: 趣味や学生、低所得国の読者には手が届かない高額なコースなど）
    • アクセシビリティのないもの（例: キャプションのない動画など）

  • 自己宣伝やスパム行為に該当するリンク: 個人的なブログ記事、カンファレンスでの講演、GitHub リポジトリーには価値がありますが、自身のリソースへのリンクは利益相反があるように見えてしまう可能性があります。ビジネスや個人的なつながりがあるリソースにリンクする前に、よく考えてください。

    メモ: リンク先とビジネスや個人的な関係がある場合は、プルリクエストでその関係を開示する必要があります。そうしないと、MDN Web Docs への継続的な参加が危ぶまれる可能性があります。

そのようなリンクが適切である場合もあります。例えば、あなたがある仕様書の編集者で、その仕様書に関連する文書化に貢献している場合、その仕様書へのリンクは期待されるものであり、許容されるものです。しかし、あなたはあなたとリンクの関係を明らかにしなければなりません。

短縮 URL

URL 短縮ツール（TinyURL や Bitly など）は、長いリンクを小さくて覚えやすい URL （「ショートリンク」とも呼ばれます）に短縮するのに最適です。しかし、これらは URL の宛先が分かりにくくなります。さらに、一部の短縮ツールでは、作成後に出力先を変更することができ、その機能を悪意のある目的に利用することができます。

サードパーティー（ユーザー生成）の URL 短縮ツールで作成したリンクは使用しないでください。例えば、 https://myshort.link/foobar がランダムなユーザーによって生成された短い URL で、 https://example.com/somelongURL/details/show?page_id=foobar にリダイレクトする場合は、長い example.com URL の方を使用してください。

一方で、リンク先の URL を管理している組織によって管理されている短縮ツールは推奨されます。 https://bugzil.la は Mozilla が自分自身で運営しており、同じく Mozilla が所有するドメインである https://bugzilla.mozilla.org/ にリダイレクトする URL 短縮ツールです。この用途では短い方の URL を使用してください。例えば、 https://bugzil.la/1682349 を https://bugzilla.mozilla.org/show_bug.cgi?id=1682349 の代わりに使用してください。

見出しレベル

新しい段落で新しい節を開始するとき、ヘッダーを追加する必要があります。 markdown の見出しレベルをスキップすることなく、小さい順に使用してください。 ##, 次に ###, そして次に ### という具合にです。これらはそれぞれ HTML 見出しタグの <h2>、<h3>、<h4> タグに翻訳されます。

# はページタイトルとして予約されているため、## が許可される最も高いレベルです。 3 レベルより上のヘッダーを追加しないことをお勧めします。もし、4 レベル目のヘッダーを追加する必要性を感じたら、この記事をいくつかの小さな記事に分割し、ランディングページを設けることを検討してください。あるいは、4 レベル目のヘッダーレベルを避けるために、情報を箇条書きで表示することができないか確認してください。

サブセクションの見出しを作成する際には、以下のことに行うべき点、行うべきでない点に留意してください。

  • 単一のサブセクションを作らないでください。 トピックを 1 つのサブトピックに分割しないでください。 2 つ以上のサブ見出しを用意するか、まったくないかのどちらかです。
  • 見出しの中でインラインスタイル、クラス、マクロを使わないでください。 ただし、コード用語を示すためにバッククオートを使用することはできます（例: "Using FooBar interface" など）。
  • "bumping heads" を作らないようにしましょう。これらは、見出しの後にすぐに小見出しが続き、その間にコンテンツテキストがない状態です。 これは見栄えが悪く、読者には外側の節の最初に何の説明もないままになってしまいます。

画像やその他のメディア

ページ内に画像やその他のメディアを載せる場合は、以下のガイドラインに従ってください。

リスト

リストは、すべてのページで一貫した形式と構造を持つ必要があります。 個々のリストアイテムは、リストの形式に関係なく、適切な句読点を使用して書く必要があります。 ただし、作成するリストの型によっては、以下の一覧で説明するように記述を調整することをお勧めします。いずれの場合も、リスト内の情報を記述する導入文を載せてください。

  • 箇条書きリスト: 箇条書きリストは、関連する簡潔な情報をグループ化するために使用してください。リストの各アイテムは、同じような文の構成に従わなければなりません。箇条書きリストの文や句（動詞や主語、あるいはその両方が欠けている文の断片）は、標準的な句読点を記載してください。文はピリオドで終わり、句はピリオドで終わりません。

    リストアイテムに複数の文がある場合、段落で期待されるのと同じように、アイテムの最後の文を含め、それぞれの文の終わりにピリオドを置かなければなりません。これは正しく構成された箇条書きリストの例です：

    この例では、以下のようなことを掲載してください。

    • 条件と、短い説明。
    • 同様に条件と、短い説明。
    • さらに条件と、さらなる説明。

    箇条書きから箇条書きへ、同じ文型が繰り返されていることに注目してください。 この例では、それぞれの箇条書きに条件が続き、カンマと簡単な説明があり、リストの各項目はピリオドで終わっています。

    リストアイテムに不完全な文章が記載されている場合、次のように行末にピリオドは必要ありません。

    このシナリオでは、以下の色関連のプロパティが役立ちます。

    • propertyA: 背景色を設定
    • propertyB: テキストに影を追加

    リストアイテムが3語以下の場合でも、1つ以上のリストアイテムが完全に文である場合は、すべてのリストアイテムの後にピリオドを使用 してください。しかし、可能な限り、リスト内のすべてのアイテムについて同じ構造に従ってください。すべてのリストアイテムが完全な文または句であることを確認してください。

  • 番号付きリスト: 番号付きリストは、主に一連の命令の手順を列挙するために使用されます。 指示は複雑な場合があるので、特に各リスト項目のテキストが長い場合は、明確にすることが優先されます。 箇条書きのリストと同様に、標準的な句読点の使い方に従ってください。正しく構成された番号付きリストの例です。

    番号付きリストを正しく構成するには、次のようにします。

    1. 冒頭に見出しや簡単な段落を設け、説明文を紹介します。説明を始める前に、ユーザーにコンテキストを提供することが重要です。
    2. 手順の作成を開始し、各ステップを独自の番号付きアイテムで管理します。 手順の作成に取り掛かり、各手順に番号を振ってください。手順がかなり広範囲に及ぶ可能性があるため、句読点を正しく使用して明確に記述することが重要です。
    3. 手順が終わったら、番号のついたリストの後に、完了時に期待される結果について、簡単な要約や説明を書きます。

    これは、締めくくりの説明の書き方の例です。

    正しい書式で番号付きリストを作成するための手順を説明した短い番号付きリストを作成しました。

    番号付きリストの項目が、短い段落のように読めることに注意してください。番号付きリストは、説明のために日常的に使用されたり、誰かを整然とした手順で案内したりするため、各項目を 1 ステップにつき 1 つの番号付き項目というように、焦点を絞るようにしましょう。

関連情報の節

MDN Web Docs のほとんどのガイド、リファレンスページ、そして用語集ページには、記事の終わりに 関連情報 節があります。この節には MDN 内の関連トピックへの 相互参照があり、時には関連する外部記事へのリンクもあります。例えば、この例は @layer ページの関連情報の節です。

一般的に、関連情報の節のリンクは箇条書きリスト形式で、リストの各アイテムを句として表示します。しかし、MDNのウェブ開発を学習する領域では、関連情報の節は定義リスト形式に続きます。

MDN Web Docs 全体の一貫性を保つため、関連情報の節を追加または更新する際は、以下のガイドラインに注意してください。

リンクテキスト

  • リンクテキストはリンク先のページや節のタイトルと同じでなければなりません。例えば、この ARIA ページのページタイトル「ARIA の状態とプロパティ」へのリンクテキストは次のようになります。
  • リンクテキストは大文字小文字は、リンク先のページタイトルやセクションタイトルと異なっていても、文の大文字小文字を使用してください。ページや節のタイトルで使用している用途が正しくない可能性があります。例えば、 Quirks Mode ページへのリンクテキストを正しい大文字小文字で書くと、次のようになります。
  • 外部リンクの場合も、対象とする記事ページのケーシングが異なっていても、文の大文字小文字を使用してください。これは MDN Web Docs 全体の一貫性を確実に保持するためです。書籍名等は例外です。
  • MDN では、リファレンスページへのリンクの節で説明されているように、オプションでマクロを使用することができます。マクロを使用すると、次の例に示すように、リンクテキストのキーワードにコード形式が追加されます。
  • リンクリストアイテムの先頭に冠詞 ("A", "An", "The") は必要ありません。リストアイテムの終わりには句読点は要求されません。
  • 上の例で示したように、ページタイトルや節タイトルでは書式を使用しない場合でも、リンクテキストのキーワードやリテラルの部分にバックティック (`) を使用してコード書式化を追加してください。例えば、 "Array() constructor" というページタイトルの場合、リンクテキストは Array() constructor となります。

説明的なテキスト

  • リンクを囲む説明文は最小限にしてください。説明文がある場合は、リンクテキストとコロンの後に追加します。説明文は語尾に句読点をつけず、句として記述してください。リンクのリストを拾いやすくするため、リンクテキストはすべて先頭に記述してください。
    • 正: :checked, :indeterminate: チェックボックスをスタイル設定するための CSS セレクター
  • 一連のアイテムの最後の前に接続詞 "and" を使用しないでください。
  • 外部リンクについては、可能かつ適切な限り、ウェブサイトと発行年または最終更新年（括弧内）を指定することを目指しましょう。この情報を前もって提供することで、読者はリンクをクリックしたときにたどり着く先について明確な考えを持つことができます。発行日または最終更新日は、読者がリンク先の記事の関連性を評価する際のガイドになりますし、 MDN 管理者が長い間更新されていない記事へのリンクをレビューする際にも役立ちます。例えばウィキペディアの記事へのリンクを指定する場合、公開・更新日は無視してもかまいません。次のリストアイテムは、外部記事の Top-level await へのリンクを関連情報セクションに、出典と年の情報とともに追加する例です。
  • 書籍への外部リンクの場合、著者名を提供することもできます。この例は、下記のFurther reading節にいくつかあります。ブログ記事や GitHub リポジトリーへのリンクの場合は、著者名を追加するのは控えましょう。

リンクの順序

  • MDNページへのリンクはリファレンスページを最初に、関連ガイドやチュートリアルページへのリンクを後に並べます。この推奨されている順序は、主にリスト内のアイテムを見つけやすくするためです。
  • 内部リンクと外部リンクが混在している場合は、内部リンクを最初に掲載し、次に外部リンクを掲載します。
  • 内部リンクと外部リンクの各グループの中では、アルファベット順か単純から高度な順のいずれかに従ってください。

サブページ

あるトピックや主題分野についていくつかの記事を追加する必要がある場合、通常、ランディングページを作成し、次に個々の記事のためのサブページを追加することによってそれを行います。 ランディングページの冒頭には、トピックや技術を記述する 1 つまたは 2 つの段落を設け、次に、各ページの説明を含むサブページのリストを提供する必要があります。 いくつかのマクロを使用すると、リストへのページの挿入を自動化することができます。

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

記事を階層の一番上に置くと、サイトの動作が遅くなり、検索やサイトのナビゲーションが効かなくなるので、なるべく避けましょう。

スラッグ

ページの上部に表示されるページタイトルは、ページの URL の <locale>/docs/ に続く部分であるページの「スラッグ」と異なるものにすることができます。スラッグを定義する際には、以下のガイドラインを念頭に置いてください。

  • スラッグは短くしましょう。新しいレベルの階層を作成する場合、スラッグの中の新しいレベルの成分は 1 語か 2 語だけにします。
  • スラッグでは、複数の単語からなる成分にはアンダースコアを使用します。例えば、/ja/docs/Learn/HTML/Introduction_to_HTML/Getting_started では Getting_started を使用します。
  • スラッグでも、それぞれの成分の大文字小文字を使い分けるにあたって、前述の例の Getting_started のように文スタイルの大文字化を使用してください。

タイトル

ページタイトルは検索結果や、ページの先頭にあるパンくずリストのページ階層を構造化するために使用されます。ページタイトルは、スラッグの節にあるように、ページの「スラッグ」とは異なっていても構いません。

タイトルを書く際には、以下のガイドラインに従ってください。

  • タイトルの大文字小文字の使用: ページタイトルセクションの見出しには、文スタイルの大文字化（文頭と固有名詞の始めの 1 字だけを大文字にする）を用いてください。一般的な見出しスタイルの大文字化は用いません。

    • 正: "A new method for creating JavaScript rollovers"
    • 誤: "A New Method for Creating JavaScript Rollovers"

    この表記ルールが確立するより前の古い記事が多くあります。必要により気軽に書き換えてください。少しずつ対応していきます。

  • 全般的なガイドライン: 何を文書化し、その内容をどのように構成するかを決めることは、文章を書く上での最初のステップの1つです。目次を書くことで、情報をどのように並べるかを決めることができます。簡単な概念から始めて、より複雑で高度な概念に応じる。概念的な情報を最初に取り上げ、次に行動的なトピックに移ってください。

    ページや節、項のタイトルを書くときは、以下のガイドラインを念頭に置いてください。

    • 高いところから低いところへ。見出しレベルの節で述べたように、レベルを飛ばすことなく、上位の ## から下位の ## へと進んでください。より広い入門的なタイトルにはより高いレベルの見出しを使用し、より低いレベルの見出しに進むにつれて、より具体的なタイトルを使用するようにしてください。
    • 論理的にグループ化する。関連するすべての項が、より高いレベルの見出しの下に論理的にまとめられていることを確認してください。この作業では、各セクションのタイトルに名前を付けると便利です。
    • タイトルを短くする。タイトルを短くすると、テキストや目次で拾いやすくなります。
    • タイトルは具体的なものにする。タイトルは、この章で使用される具体的な情報を伝えるために使用します。例えば、 HTML 要素を紹介する部分では、「導入」や「概要」ではなく、「HTML 要素」というタイトルを使用してください。
    • タイトルは焦点を絞る。タイトルは、 1 つの目的、この部分に応じた 1 つのアイデアや概念を伝えるために使用します。そのため、タイトルにはできるだけ、接続詞の「および」を使用しないようにしましょう。
    • 並列構造を使用する。 同じ見出しレベルのタイトルには類似した言葉を使用してください。例えば、 ### 見出しレベルのタイトルが "Installing" のように "-ing" で終わる単語、つまり動名詞を使用している場合、その見出しレベルのタイトルはすべて動名詞を使用して書くようにしてください。タイトルが "Use", "Configure" などの命令形動詞で始まる場合は、その見出しレベルのタイトルはすべて命令形動詞で始まるように書いてください。
    • 下層部の見出しに共通する語を使わない: 上位の見出しのテキストを下位の見出しで繰り返さない。例えば、「カンマ」というタイトルのコーナーでは、サブセクションのタイトルを「導入句の後のカンマ」ではなく、「導入句の後」と名付けてください。
    • 冠詞で始めない。 タイトルを冠詞「a」、「an」、「the」で始めるのは避けてください。
    • 導入情報を追加する。タイトルの後で、この部分で取り上げられる内容を説明するために、いくつかの導入テキストを追加してください。

関連情報

その他の情報

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

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

言語、文法、綴り

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