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