Writing style guide

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

あるタイプのページをどのように構成するべきかについて詳細を知りたければ、MDN ページレイアウトガイドを参照してください。

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

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 ガイドを見てみましょう。以下のような構造になっています。

JavaScript/Guide - メインの目次となるページ
JavaScript/Guide/JavaScript Overview
JavaScript/Guide/Functions
JavaScript/Guide/Details of the Object Model

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

セクション、パラグラフ、改行

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

Enter (かReturn) キーは新しいパラグラフを開始します。空行無しに改行したい場合は、Shift キーと Enter キーを同時押ししてください。

単独のサブセクションを作らないでください。トピックを一つに分割するというのは意味のわからないことです。2つ以上のサブ見出しを用意するか、まったくないかのどちらかです。

立て続けに見出しを続けるのをやめてください。見た目は悪くても読み手にとっては見出しのあとに以降のサブセクションを紹介する手短な導入部があるほうが親切です。

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

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

注記: "注記" は重要な注意を呼びかけるのに使われます。こんな感じです。

警告:同様に、"警告" は警告ボックスをこのように作成します。

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

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

タブと改行

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

例:

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

水平にスクロールしなければならないほど長い行は、自然な位置で改行するべきです。

いくつかの例:

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() のように。括弧があることでメソッドとその他のコードの用語を区別できます。

シンタックスハイライト

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

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

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

x = 42;

HTML 要素リファレンスのスタイル

HTML 要素について記述するときに従うべきルールは様々あります。これに従うと、HTML 要素とそのコンポーネントについて首尾一貫した記述が生成され、適切なリンクと詳細なドキュメンテーションも保証されます。

要素名: HTMLElementマクロを使って下さい。その要素用のページへのリンクを生成します。例えば、{{HTMLElement("title")}}と書けば、"<title>"と出力されます。リンクを作りたくなければ、角括弧（"<>"）で名前を囲んで行中に埋め込むコードのスタイルで書いてください（例えば、 <title>）。
属性名: 太字で記述してください。
属性定義: 定義名にはhtmlattrdefマクロを使用してください（例えば、{{htmlattrdef("type")}}）。他記事からのリンクを貼ることができます。次に属性定義を参照するためにhtmlattrxrefマクロを使用してください（例えば、 {{htmlattrxref("attr","element")}}）。
属性値: "文中でのコード"スタイルで書いて下さい。文字列を引用符で囲まないでください、ただしコードサンプルのシンタックスハイライトの為に必要な場合は別です。例えば: When the type attribute of an <input> element is set to email or tel ...
属性にラベルをつける: HTML5のようなラベルをよく考えて使用してください。例えば、太字の要素名の後などに続けて書くのが好ましいですが、文章中に現れるたびに書くのはやめましょう。

ラテン語の略記

注釈と括弧内で

よく使われるラテン語の略記（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

大文字の使用

文章中では、英語における標準的な大文字のルールに従ってください。"World Wide Web" や "Web"のようにしてください。

キーボードのキー名は通常の文におけるスタイルで大文字を使用してください。全部大文字にするのはやめてください。"Enter"が正しく、"ENTER"は誤りです。

短縮形

書体はカジュアルで構いません。なので気軽に短縮形を使ってください（例えば、"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 のやり方はこのルールの例外です。

綴りの統一

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

正しい: localize, honor
間違い: localise, honour

専門用語

Obsolete（廃止）か、Deprecated（非推奨）か

廃止されたのか、非推奨なのかを明確に区別するのは重要です。

Obsolete（廃止）:: MDNにおいては、Obsolete（廃止）という用語は、ただ非推奨なだけでなくブラウザで実行されないAPIやテクノロジーを指しています。Mozilla のテクノロジーに限って言えば、そのAPIがMozilla のコードで実装されていないものを指します。Web標準のテクノロジーについて言えば、そのAPIや機能は、現在の一般的に使われているブラウザではサポートされていないものを指します。
Deprecated（非推奨）:: MDNにおいては、Deprecated（非推奨）という用語は、非推奨だがいまだ実装されていて、動作することもあるAPIやテクノロジー、を指します。これらの技術は原則、廃止され除去されます。したがって、使用をやめるべきです。Mozilla のテクノロジーについて言えば、そのAPIはまだMozilla コード上で実行されます。Web標準のテクノロジーについて言えば、そのAPIまたは機能は、標準となりつつあるバージョンでは既に置き換えられ、除去されてしまっているものを指します。

HTML 要素

"要素" は、"タグ" ではなく、 HTML と XML との要素を指します。また、要素は常に "<>" 内に記述されるべきで、<code> のスタイルに従うべきです。それから、少なくとも記事においてその要素について初めて言及する際はHTMLElement マクロを利用してください。その要素についてのドキュメンテーションへのリンクが生成されます。ただしまさにその要素についてのリファレンス記事を作成している場合は必要ありません。

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

ユーザインターフェイス

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

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

受動態か能動態か

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

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

リンク

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

外部リンク

Bugzilla のバグへのリンクを自動生成するためには、以下のマクロを利用してください。

{{Bug(322603)}}

結果はこうなります、

バグ 322603

WebKit のバグには以下のマクロを利用してください。

{{Webkitbug("322603")}}

結果はこうなります、

WebKit bug 322603

URL スキーム

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

https://
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" スタイルを利用してセクションをマークすることで上書きすることができます。

ランディングページ

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

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

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

MDN ランディングページのリンクリストセクションは２段組からなります。下記の 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>>>

イメージの利用と挿入

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

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

その他のリファレンス

MDN 独自の内容について

MDN のMDN Commonly-used macros に説明があります。

言語、文法、綴り

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

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.