用語集の項目を書いたり参照したりするには
この記事では、 MDN Web Docs の用語集に項目を追加したりリンクしたりする方法について説明します。 また、用語集の項目のレイアウトと内容に関するガイドラインも提供します。 用語集には、ウェブやウェブ開発に関する MDN コンテンツを読む際に出くわすであろうすべての用語、専門用語、略語、頭字語の定義が記載されています。
ウェブは常に変化しているため、用語集が完全ではない可能性があります。 新しい項目を投稿したり、問題を修正したりすることで、用語集の更新やギャップを埋めることができます。
用語集に寄稿することは、誰にとってもウェブをより理解しやすくするための簡単な方法です。 高度な技術的スキルは必要ありません。 用語集の項目は、簡単で簡潔なものを目指しています。
項目を執筆する方法
用語集に項目が必要なトピックを探している場合は、文書化されていない用語のリストが用語集のランディングページの最後にあるので確認してください。これらのリンクをクリックすると、クリックした項目の新しい用語ページが開きます。それから、次の手順に従ってください。
新たなトピックについての考えがあるならば、 glossary ランディングページ 付近に新しいページを作成してください。
要約を書く
用語集ページの最初の段落は、その用語の簡潔で短い説明です。 できれば、 2 文以内にしてください。 説明を読めばどんな人であってもただちに理解できるような説明であるようにしてください。
メモ: インターネット上にある他の定義やコンテンツをコピー＆ペーストしないでください。 （特にウィキペディアは、ライセンスの版の幅が小さいため、 MDN とは互換性がありません。）用語集の項目は独自の内容にしてください。
良い用語集の項目を書く
必要であれば、いくつかの段落を追加してください。しかし、気がつくと、全体の記事を書いていることがあります。 記事を書くのは構いませんが、用語集には行わないでください。 記事をどこに置けばよいかわからない場合は、お気軽に相談してください。
より良い用語集の項目を書くために考慮すべき簡単なガイドラインがいくつかあります。
- 用語集の説明文で用語を使用するときや、略語を使用するときには、適切なリンクを作成してください。 多くの場合、これは用語集の他のページへのリンクを作成するだけです。
- 用語集の項目では、記事を追いかけるのが難しくせずにできるのであれば、適切な関連用語を（リンク付きで）使用してください。 関連した有用なリンクのネットワークを持つことで、ページ、または一連のページを使いやすくすることができます。
- このページを見つけたいと思ったときに、どのような検索用語を選ぶか考えてみてください。 その用語を検索するために使用するすべての単語を使用してみてください。ただし、用語集の項目を無意味にしたり、長くしたり、読みにくくしたりしないようにしてください。
リンクで拡張する
用語集の項目は常に詳細情報の節で終わらせてください。この節では、読者が先へ進むための手助けとなるリンクを含むようにしてください。例えば、さらなる詳細がわかるようになるもの、関連した技術を学ぶことができるものなどです。
リンクは少なくとも以下の 3 つのグループに分けることをおすすめします。
- 一般知識
-
その用語や主題についてのより高水準な情報を提供するリンク群です。例えば、関連する Wikipedia ページへのリンクです。
- 技術情報
-
MDN Web Docs もしくは外部サイトにある、より詳細な技術情報へのリンク群です。
- 学習素材
-
読者がその用語の背景にある技術の利用方法を学ぶことを支援する、チュートリアルや演習問題、その他の素材へのリンク群です。
曖昧な言葉の扱い
言葉によっては、文脈によって複数の意味を持つことがあります。曖昧さを解決するために、以下のガイドラインに従ってください。
- 用語の主ページは、
GlossaryDisambiguationマクロを含む曖昧さを表すページでなければなりません。 - それぞれの文脈に応じた用語を定義する副ページを設置してください。
例を用いて説明します。 signature という用語は、セキュリティ、関数、メールなど 3 種類以上の文脈で異なる意味持ちます。
- Glossary/Signature のページは
GlossaryDisambiguationマクロを含む曖昧さを表すページです。 - Glossary/Signature/Security ページはセキュリティの文脈における署名を定義しているページです。
- Glossary/Signature/Function ページは関数シグネチャを定義しているページです。