用語集の項目を書いたり参照したりするには

この記事では、 MDN Web Docs の用語集に項目を追加したりリンクしたりする方法について説明します。また、用語集の項目のレイアウトと内容に関するガイドラインも提供します。用語集には、ウェブやウェブ開発に関する MDN コンテンツを読む際に出くわすであろうすべての用語、専門用語、略語、頭字語の定義が記載されています。

ウェブは常に変化しているため、用語集が完全ではない可能性があります。新しいエントリを投稿したり、問題を修正したりすることで、用語集の更新やギャップを埋めることができます。

用語集に寄稿することは、誰にとってもウェブをより理解しやすくするための簡単な方法です。高度な技術的スキルは必要ありません。用語集の項目は、簡単で簡潔なものを意図しています。

項目を執筆する方法

用語集に項目が必要なトピックを探している場合は、文書化されていない用語のリストが用語集のランディングページの最後にあるので確認してください。これらのリンクをクリックすると、クリックした項目の新しい用語ページが開きます。それから、次の手順に従ってください。

新たなトピックについての考えがあるならば、新しいタブで以下のボタンを開き、ボタンよりも下にある手順通りにしてください。

ステップ1: 説明する用語を選ぶ

用語集に追加する用語を選択します。どの用語の定義が必要かわからない場合は、提案の一覧を見ることができます。いずれかの用語をクリックすると、始めることができます。すでにログインしている場合は、用語をクリックすると MDN エディターが開きます。

ステップ2: 要約を書く

用語集ページの最初の段落は、その用語の簡潔で短い説明です。できれば、2文以内にしてください。説明を読めばどんな人であってもただちに理解できるような説明であるようにしてください。

良い用語集の項目を書く

必要であれば多少は段落を追加しても良いのですが、気が付くと記事全体を書いてしまいがちです。記事を書くことはすばらしいのですが、用語集の中には作成しないでください。記事をどこに書けばよいのかわからない場合は、気軽に相談してください。

より良い用語集の項目を書くために考慮すべき簡単なガイドラインがいくつかあります。

• 用語集の説明文で用語を使用するときや、略語を使用するときには、適切なリンクを作成してください。多くの場合、これは用語集の他のページへのリンクを作成するだけです。 (下記の Glossary マクロの使い方を参照してください。) 用語集の項目の用語に直接関連する用語については、 MDN Web Docs のメイン記事にリンクしてください。
• 用語集の項目では、記事を追いかけるのが難しくせずにできるのであれば、適切な関連用語 (リンク付きで) を使用してください。関連した有用なリンクのネットワークを持つことで、ページ、または一連のページを使いやすくすることができます。
• このページを見つけたいと思ったときに、どのような検索用語を選ぶか考えてみてください。その用語を検索するために使用するすべての単語を使用してみてください。ただし、用語集の項目を無意味にしたり、長くしたり、読みにくくしたりしないようにしてください。

ツールチップの設定

ほとんどの MDN リンクと同様に、用語集のリンクにカーソルを合わせると、ページの簡単な説明 (この場合、用語の定義の短い要約) が表示されます。既定ででは、ツールチップは用語集の項目の最初の段落全体のテキストを取ります。これはふつうは長すぎます。

別の方法として、テキストの一部区間をページの概要として割り当てることもできます (これがツールチップのテキストにもなります)。用語の定義を要約する1～2文を選択し、選択されたテキストに SEO Summary スタイルを追加してください。これでツールチップのテキストが定義されます。また、これはページの内容の要約として検索エンジンに送信されるテキストに割り当てられます。そのため、ページの要約を具体的に選択することで、あなたの仕事が検索結果でより目に付くようになります。

ステップ3:リンクで拡張する

用語集の項目は常に詳細情報の節で終わらせてください。この節では、読者が先へ進むための手助けとなるリンクを含むようにしてください。例えば、さらなる詳細がわかるようになるもの、関連した技術を学ぶことができるものなどです。

リンクは少なくとも以下の3つのグループに分けることをおすすめします。

一般知識

その用語や主題についてのより高水準な情報を提供するリンク群です。例えば、関連する Wikipedia ページへのリンクです。

技術情報

MDN Web Docs もしくは外部サイトにある、より詳細な技術情報へのリンク群です。

学習素材

読者がその用語の背景にある技術の利用方法を学ぶことを支援する、チュートリアルや演習問題、その他の素材へのリンク群です。

曖昧な言葉の扱い

言葉によっては、文脈によって複数の意味を持つことがあります。曖昧さを解決するために、以下のガイドラインに従ってください。

• 用語の主ページは、 GlossaryDisambiguation マクロを含む曖昧さを表すページでなければなりません。
• それぞれの文脈に応じた用語を定義する副ページを設置します。

例を用いて説明します。 signature という用語は、セキュリティ、関数、メールなど3種類以上の文脈で異なる意味持ちます。

1. Glossary/Signature のページは GlossaryDisambiguation マクロを含む曖昧さを表すページです。
2. Glossary/Signature/Security ページはセキュリティの文脈における署名を定義しているページです。
3. Glossary/Signature/Function ページは関数シグネチャを定義しているページです。
4. Glossary/Signature/Email ページはメールの署名を定義しているページです。

{{Glossary}} マクロの使い方

用語集は、人々が他の文書からそこから移動することなしに定義にアクセスできると、より役立ちます。そこで、いつでも用語集にリンクできる Glossary マクロを使うことをおすすめします。

{{Glossary}} マクロを用いて作成されたリンクは、用語集の項目における要約の段落、または SEO summary (前述の ツールチップの設定 の節で解説) として定義されたテキストを含むツールチップを表示します。

マクロの賢い使用

多くの場合、 MDN のあらゆる場所でこのマクロを用いるのはまったく問題がありません。 {{Glossary}} マクロを使用するには以下のガイドラインを考慮してください。

• ある用語に既に MDN の適切なページへのリンクが設定されている場合は、用語集のリンクに置き換えないでください。
• 記事の1つの節の中では、 {{Glossary}} マクロは同じ用語に対して1度しか使わないでください。記事の節は常にタイトルから始まるので、見分けることができます。