執筆スタイルガイド

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

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

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

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

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

一般的なガイドラインを記載した後、このガイドでは 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() メソッドのより良い概要を見てみましょう。

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

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

差別的でない言葉

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

  • master (マスター)や slave (スレーブ)という用語を避け、 main (メイン)や replica (レプリカ)を使用してください。
  • whitelist (ホワイトリスト)や blacklist (ブラックリスト)を allowlist (許可リスト)や denylist (拒否リスト)に置き換えてください。
  • sanity (正気)は coherence (正常性)に置き換えてください。
  • dummy (ダミー)の代わりに placeholder (プレイスホルダー)を使用してください。
  • 文書で crazyinsane を使用する必要はありませんが、場合によっては 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 ガイドラインには、執筆者や編集者が作業する各ページが、検索エンジンが記事を適切にインデックスするために必要な文脈や手がかりを与えるよう、合理的に設計され、書かれ、マークアップされていることを確認することが含まれます。

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

  • ページが似すぎていないことを確認する。このページのコンテンツがテキスト的に似ていると、検索エンジンは、たとえそうでなくても、そのページが同じことについて書かれているとみなしてしまいます。 例えば、あるインターフェイスに widthheight というプロパティがある場合、この 2 つのプロパティを文書化した 2 つのページでは、いくつかの単語を入れ替えたり、同じ例を使用するだけで、驚くほど似たような文章になりがちです。これでは、検索エンジンはどちらがどちらかわからなくなり、ページランクを共有することになり、結果的にどちらも見つけるのが難しくなってしまいます。 そこで、すべてのページが自身のコンテンツを保有することが重要です。ここでは、そのためのヒントをいくつかご紹介します。
    • より固有な概念を説明する。意外と違いがあるかもしれない使用例を考えてみます。例えば、 widthheight のケースでは、水平方向の空間と垂直方向の空間がどのように異なる使い方をされているかを考え、適切な概念についての議論を行います。例えば、幅についてはサイドバーを設置するための空間として、高さについては縦方向のスクロールやフッターなどのために使用することを考えます。また、アクセシビリティの問題についての情報を盛り込むことも、有用かつ重要なアイデアです。
    • 異なる例を使用する。各ページにまったく異なる例を使ってください。このような場合の例は、本文よりもさらに似通っていることが多いものです。というのも、例はそもそも似たようなメソッドやプロパティの両方(またはすべて)を使用していることがあり、再利用する際に実質的な変更を必要としないからです。そのため、例を捨てて新しい例を書くか、少なくとも複数の例を用意し、そのうちのいくつかは異なる例文してください。
    • 例に説明文を追加する。それぞれの例について説明を加えてください。トピックの複雑さと対象読者を考慮して、適切なレベルの詳細で、例が何をするのかという概要と、どのように機能するのかという説明の両方を含める必要があります。
    同じような内容になりすぎないようにするには、時間が許す限り、それぞれの記事を一から書き直すのが一番簡単です。
  • このページが短すぎないようにする。ページの内容が小さすぎると(SEO 用語で「薄いページ」と呼ばれます)、検索エンジンは正確なカタログ化が困難です。短すぎるコンテンツページは探すのが大変です。 MDN Web Docs のページは、可能な限り 300 語前後よりも短くしないでください。人為的にページを膨らませるのではなく、可能な限りこのガイドラインを最小の目安となる長さとして扱ってください。 このページでは、不要なテキストでごちゃごちゃさせることなく、適切に検索できるような十分なコンテンツを保有するページを作成するための基本的なガイドラインをご紹介します。
    • スタブを避ける。明らかに記事がスタブであったり、内容が不足している場合は、追加してください。 MDN Web Docs では、完全な「スタブ」ページは避けるようにしていますが、存在します。しかし、コンテンツの大部分が欠けているページはたくさんあります。
    • ページの構成を見なおす。一般的には、ページの種類に応じて適切に構成されていることを確認してください。持つべき節がすべて存在し、適切なコンテンツがあることを確認してください。
    • 完全性を確保する。すべての節が完全で、最新の情報が含まれていることを確認してください。すべての引数がリストアップされ、説明されているか。例外がカバーされていることを確認してください(これは特にコンテンツが欠けていることが多い場所です)。
    • すべての概念が完全に具体化されていることを確認する。すべての項目が詳細に説明されているかどうか。簡単な説明をするのは簡単ですが、すべてのニュアンスが含まれているかどうかを確認してください。特別なケースはありますか?読者が知っておくべき既知の制限はありますか?
    • 例を追加する。すべての引数、あるいは少なくとも初級から中級レベルのユーザーが使用する可能性のある引数(またはプロパティや属性)と、追加の説明が必要な高度な引数を網羅した例を用意する必要があります。それぞれの例の前には、その例が何をするのか、それを理解するためにはどのような知識が必要なのかなどの概要を示す必要があります。例の後(または例の一部の間)には、コードがどのように動作するかを説明する文章が必要です。例の詳細やエラー処理についても手を抜いてはいけません。読者は例をコピー&ペーストして自分のプロジェクトで使用するでしょうから、そのコードが本番サイトで使用されることになるでしょう。より有用な情報は、コード例のガイドラインを参照してください。
    • 使用例を説明する。説明されている機能について、特に一般的な使用例がある場合は、それについて話してください。一般的な開発上の問題を解決するために文書化された方法を読者が理解すると仮定するのではなく、実際にその利用例についての節を追加し、例とその例がどのように機能するかを説明するテキストを追加してください。
    • 画像情報を追加する。すべての画像や図に適切な alt テキストを入れてください。このテキストは、表などのキャプションと同様に重要です。スパイダーは画像をクロールすることができないため、 alt テキストによって、埋め込まれたメディアに含まれるコンテンツを検索エンジンのクローラーに伝えることができます。

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

    • トピックの内容を重視する。 2013 年に行われた Google のハミングバードアップデートでは、自然言語による情報伝達が重視されるようになりました。つまり、特定のキーワードではなく、記事のトピックに沿ってコンテンツを書く方がはるかに良いということです。実際、多くの 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." を推奨します。

  • : 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, 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

複数形

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

  • : syllabuses, octopuses
  • : syllabi, octopi

区切り記号

引用符と疑問符

「曲がった」引用符と疑問符を使用しないでください。 MDN では、直線の引用符とアポストロフィのみを使用してください。これにはいくつかの理由があります。

  • 一貫性のためにどちらかを選択しなければなりません。
  • 曲がった引用符やアポストロフィがコードスニペットの中に入ってくると、インラインのものであっても、読み手はそれらをコピーして貼り付け、動作することを期待してしまうかもしれません (そうはならないでしょう)。
  • : Please don't use "curly quotes."
  • : Please don’t use “curly quotes.”

カンマ

  • 導入節の後: 導入節は従属節で、通常、文頭に現れます。導入節の後にカンマを使用し、次の独立節と区切ってください。
    • : "In this example, you will see how to use a comma."
    • : "In this example you will see how to use a comma."
    • : "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."
    • : "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 つの文として書き直すことを検討してください。
    • : "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."
    • : "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."W
    非制限節は追加情報を提供するもので、文の意味にとって不可欠なものではありません。非制限節は通常 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."

ハイフネーション

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

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

綴り

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

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

  • : localize, behavior
  • : localise, behaviour

用語

HTML 要素

HTML や XML の要素を表すには "elements" を使用し、 "tags" を使用しないでください。 加えて、基本的に常に "<>" で囲んで記述し、 <code> スタイルの中に入れてください。

その要素を節の中で初めて参照するときは、 HTMLElement マクロを使用して要素の文書へのリンクを作成してください (その要素のリファレンス文書ページ内で書いている場合を除く)。

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

parameter と argument

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

ユーザーインターフェイス操作

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

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

能動態と受動態

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

ページの構成

このコーナーでは、見出し、注釈、リンク、例など、ページによく現れる構成要素について、守るべきガイドラインを示します。

コードの例

MDN Web Docs のページには、1 つ以上のコード例を含めることができます。

MDN Web Docs のコード例を書く際に、以下のようなことを推奨します。

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

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

外部リンク

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 への継続的な参加が危ぶまれる可能性があります

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

見出しレベル

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

# はページタイトルとして予約されているため、## が許可される最も高いレベルです。 もし 3 つか 4 つ以上のレベルのヘッダーが必要な場合は、記事をいくつかの小さな記事に分割し、ランディングページを設けることを検討してください。

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

  • 単一のサブセクションを作らないでください。 トピックを一つに分割するというのは意味のわからないことです。 2 つ以上のサブ見出しを用意するか、まったくないかのどちらかです。
  • 見出しの中でスタイルやクラスを使わないでください。 これには、コード用語を書くための <code> 要素も含まれます。ですから、「SuperAmazingThing インターフェイスの使用」というような見出しを作らないようにしましょう。その代わりに、「SuperAmazingThing インターフェイスの使用」だけにすべきです。
  • 見出し内でのマクロを使用することは避けてください (見出し内で使用するように特別に設計された特定のマクロを除く)。
  • 見出しの後に内容のテキストをはさまずに小見出しが続く、 "bumping heads" を作らないようにしましょう。これは見栄えが悪く、読者には外側のセクションの最初に何の説明もないままになってしまいます。

画像やその他のメディア

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

  • メディアのライセンスが使用することを許可していることを確認してください。 CC0 のようなとても寛容なライセンスを有するメディア、または少なくとも私たちの一般的なコンテンツライセンス - クリエイティブ・コモンズ - 表示・継承ライセンス (CC-BY-SA) と互換性のあるものを使用するようにしましょう。
  • 画像の場合、https://tinypng.comまたはhttps://imageoptim.comを通すとページが軽量化されます。
  • SVG の場合は、 SVGOMG を通してコードを実行し、 SVG ファイルの最後に空行があることを確認してください。
  • ページにアイコンを表示する場合 (例: background-image) は、必要に応じて mdn-dinocons リポジトリのアイコンを使用し、その他の場合はそのスタイルに一致するようにしましょう。

リスト

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

箇条書きリスト

箇条書きリストは、関連する簡潔な情報をグループ化するために使用してください。 リストの各項目は、同じような文の構成に従わなければなりません。 箇条書きリストの語句や 文は、標準的な句読点を載せる必要があります。 箇条書きリストの各文の最後には、段落の場合と同じように、項目の最後の文も含めてピリオドを置いてください。

これは、正しく構成された箇条書きのリストの例です。

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

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

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

番号付きリスト

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

正しく構成された番号付きリストの例です。

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

  1. 冒頭に見出しや簡単な段落を設け、説明文を紹介します。説明を始める前に、ユーザーにコンテキストを提供することが重要です。
  2. 手順の作成を開始し、各ステップを独自の番号付きアイテムで管理します。

手順の作成に取り掛かり、各手順に番号を振ってください。手順がかなり広範囲に及ぶ可能性があるため、句読点を正しく使用して明確に記述することが重要です。 3. 手順が終わったら、番号のついたリストの後に、完了時に期待される結果について、簡単な要約や説明を書きます。

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

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

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

サブページ

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

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

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

タイトル

ページタイトルは検索結果や、ページの先頭にあるパンくずリストのページ階層を構造化するために使用されます。(ページの先頭や検索結果に表示される)ページタイトルは、ページの「スラッグ」とは異なっていても構いません。「スラッグ」とは、ページの URL の "<ロケール>/docs/" に続く部分のことです。

タイトルの大文字小文字の使用

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

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

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

タイトルの書き方のガイドライン

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

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

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

タイトルとスラッグ

ページのスラッグは短くしてください。

新しいレベルの階層を作成する場合、スラッグの中の新しいレベルの構成要素は、単語 1 つか 2 つのだけであるべきです。一方、ページのタイトルは、無理のない範囲で好きなだけ長くしてよく、説明的にしてください。

関連情報

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

ここで取り扱われていない用法とスタイルについて疑問があれば、 Microsoft Writing スタイルガイド を、それでもダメなら Chicago Manual of Style を参照してください。 非公式の crib sheet for the Chicago Manual of Style がオンラインで利用できます。

おすすめの辞書

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

何度もガイドが拡張されることになるでしょう。もし、このドキュメントでカバーされていない特定の質問がある場合は、連絡してください。そうすれば、何を追加すべきかが分かります。

言語、文法、綴り

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