MDNの用語集は、ドキュメントやコードにおいて用いられるすべての用語、専門用語、略語を定義するためのものです。用語集に貢献することは、すべての人にとってWebをより扱いやすくする単純な方法のひとつです。高いレベルの技術的な能力は必要ではありません。というのも、用語集は簡潔ではっきりしている必要があるからです。
この記事においては、MDN Webドキュメントのサイトにおいてどのように良い用語集の記事を書くかについて述べます。
どのようにエントリを執筆するか
もし用語集に必要なトピックを探しているなら、用語一覧ページの最後にある、まだドキュメント化されていないリスト(英語版)を確認してください。そのリストにあるリンク中からクリックして、クリックしたアイテムの用語についてのトピックの執筆を始めてください。そして、以下にあるようなステップを踏んでください。
新たなトピックについての考えがあるならば、新しいタブで以下のボタンを開き、ボタンよりも下にある手順通りにしてください。
ステップ1: 要約を書く
すべての用語のページにおける最初のパラグラフには、用語について簡潔な説明を掲載してください(できれば1文か2文で)。その説明を読めばどんな人であってもただちに理解できるような説明であるように心がけてください。
注意: 絶対に定義(や説明)をどこかしらからコピー・ペーストするということはしないでください(特に Wikipedia から。というのもご存知のように Wikipedia はライセンスのバージョンが少なく、ゆえに MDN のライセンス体系とは適合しないからです)。 コンテンツの内容が簡潔かつ明瞭であることが本当に重要です。 同じ時間を過ごすならば、内容を見ずにどこかから盗むよりもむしろコンテンツの内容を簡潔かつ明瞭にするほうが価値があります。 この用語集は新しいコンテンツであるこそ便利なのであり、どこかにあるようなことを繰り返すこととは異なります。
用語集の各記事へのリンクは、自身のツールチップの中にこれらの要約を用います。ですので、読者たちはその時点で閲覧しているページから動くことをせずに定義を確認できます。( {{Glossary}} マクロを用いて用語集の記事にリンクを挿入する方法については、以下を参照してください。)
必要なら、ほんの少しの補足パラグラフを追加できますが、ひとつの記事を書くことはとても簡単です。ひとつの記事を書くことは素晴らしいですが、それを用語集の中に追加しないでください。あなたの記事をどこに追加すべきかわからないときは、お気軽に相談してください。
ステップ2:リンクで拡張する
最終的に、用語集のエントリは "詳細情報" セクションで常に終わるべきです。このセクションは、読者が先へ進むための手助けとなるリンクを含むべきです。例えば、さらなる詳細がわかるようになるもの、関連した技術を学ぶことができるものなどです。
リンクは少なくとも以下の3つのグループに分けることをおすすめします。
- 一般的・抽象的な知識
- より一般的な情報を提供するリンク群。例えば、Wikipedia へのリンクは良いスタートポイントです。
- 技術的に参考になる情報
- MDN、もしくは外部サイトにある、より詳細な技術情報へのリンク群。
- それについて学ぶ
- 読者がその用語の背景にある技術の利用方法を学ぶことを支援する、チュートリアルや演習問題、その他の素材へのリンク群。
推薦される用語
さて、用語集について貢献したいけどどの用語が定義される必要がわからない？ これがおすすめの用語のリストです。 1つクリックして、はじめてみましょう！
あいまいな言葉はどうする？
ある言葉は文脈によって意味が変わることがあります。 あいまいさを回避・解消するために、これらのガイドラインに必ず従ってください：
- 用語の主ページは、
GlossaryDisambiguationマクロを含むあいまいなページでなければなりません。 - 文脈に応じた意味を明確に説明した副ページが存在しなければなりません。
例を用いて説明してみます。 signature という語は、セキュリティ・機能・Eメールのような異なる文脈に応じて異なる意味を持ちます。
- Glossary/Signature ページは
GlossaryDisambiguationマクロを含むあいまいなページです。 - Glossary/Signature/Security ページはセキュリティの文脈における署名を定義しているページです。
- Glossary/Signature/Function ページは関数シグネチャを定義しているページです。
- Glossary/Signature/Email ページは E メール署名を定義しているページです。
{{Glossary}} マクロの使い方
用語集は、人々が他のドキュメントからそこから移動することなしに定義にアクセスできると、もっとより役立ちます。そこで、いつでも用語集にリンクできる Glossary マクロを使うことをおすすめします。
| マクロ | 結果 | 備考 |
|---|---|---|
| {{Glossary("browser")}} | browser | テキストは定義されている用語にそのままマッチします（大文字小文字を区別します）。 |
| {{Glossary("browser", "Web browser")}} | Web browser | 代替テキストを表示するためには、2 つ目の引数にそのテキストを指定してください。 |
| {{Glossary("browser", "Web browser", 1)}} | Web browser | 3 つ目の引数に 1 を指定することと、下線付きヒントではなく、通常のリンクとしてリンクを表示します。 |
{{Glossary}} マクロを用いて作成されたリンクは常に用語集エントリの要約パラグラフを含むツールチップを表示します。
使い方のガイドライン
多くの場合、MDN のすべての場所でこのマクロを用いて全く問題ありません。しかし、扱いに気をつけるべきいくつかのケースがあります。
- その用語が MDN の別の部分に既にリンクされている場合は、そのままにしておいて、 {{Glossary}} マクロを使わないでください。
- 記事内において、 {{Glossary}} マクロは同じ用語に対して 1 度のみ使ってください（ヒント：セクションは常にタイトルから始まります）。