この翻訳は不完全です。英語から この記事を翻訳 してください。

MDNの用語集で、ドキュメントやコードにおいて我々が用いるすべての専門用語や略語を定義、すなわち意味を明らかにします。用語集に貢献することは、すべての人にとってWebがより扱いやすくする単純な方法のひとつです。高いレベルの技術的な能力は必要ではありません。というのも、用語集は簡潔ではっきりしている必要があるからです。 この記事においては、MDN Webドキュメントのサイトにおいてどのように良い用語集の記事を書くかについて述べます。

どのようにエントリを執筆するか

もし用語集に必要なトピックを探しているなら、Glossary landing pageの最後にある、まだドキュメント化されていないリストを確認してください。そのリストにあるリンク中からクリックして、クリックしたアイテムの用語についてのトピックの執筆を始めてください。そして、以下にあるようなステップを踏んでください。

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

 

ステップ1: 要約を書く

すべての用語のページにおける最初のパラグラフには、用語について簡潔な説明を掲載してください(できれば1文か2文で)。その説明を読めばどんな人であってもただちに理解できるような説明であるように心がけてください。

注意: 絶対に定義(や説明)をどこかしらからコピー・ペーストするということはしないでください(特にWikipediaから。というのもご存知のようにWikipediaはライセンスのバージョンが少なく、ゆえにMDNのライセンス体系とは適合しないからです)。 コンテンツの内容が簡潔かつ明瞭であることが本当に重要です。 同じ時間を過ごすならば、内容を見ずにどこかから盗むよりもむしろコンテンツの内容を簡潔かつ明瞭にするほうが価値があります。 この用語集は新しいコンテンツであるこそ便利なのであり、どこかにあるようなことを繰り返すこととは異なります。

用語集の各記事へのリンクは、自身のtooltipsの中にこれらの要約を用います。ですので、読者たちはその時点で閲覧しているページから動くことをせずに定義を確認できます。( {{Glossary}} マクロを用いて用語集の記事にリンクを挿入する方法については、以下を参照してください。)

If you must, you can add a few extra paragraphs, but it's very easy to find yourself writing a whole article. Writing a whole article is fine, but please don't put it in the glossary. If you aren't sure where to put your article, feel free to reach out to discuss it.

ステップ2:リンクで拡大する

Finally, a glossary entry should always end with a "Learn more" section. This section should contain links to help the reader move forward: discovering more details, learning to use the relevant technology, and so on.

We recommend that you sort the links into at least these three groups:

一般的・抽象的な知識
Links that provide more general information; for example, a link to Wikipedia is a good starting point.
技術的に参考になる情報
Links to more in-depth technical information, on MDN or elsewhere.
それについて学ぶ
Links to tutorials, exercises, or any other materials that help the reader learn to use the technology behind the defined term.

推薦される用語

さて、用語集について貢献したいけどどの用語が定義される必要がわからない? これがおすすめの用語のリストです。 1つクリックして、はじめてみましょう!

あいまいな言葉はどうする?

ある言葉は文脈によって意味が変わることがあります。 あいまいさを回避・解消するために、これらのガイドラインに必ず従ってください:

  • 用語の主ページは、 GlossaryDisambiguation マクロを含むあいまいなページでなければなりません。
  • 文脈に応じた意味を明確に説明した副ページが存在しなければなりません。

例を用いて説明してみます。signatureという語は、セキュリティ・機能・Eメールのような異なる文脈に応じて異なる意味を持ちます。

  1. The page Glossary/Signature is the disambiguation page with the GlossaryDisambiguation macro.
  2. The page Glossary/Signature/Security is the page defining a signature in a security context.
  3. The page Glossary/Signature/Function is the page defining a function signature.
  4. The page Glossary/Signature/Email is the page defining email signature.

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

The glossary is much more useful when people can access the definitions from another document without navigating away from what they're reading. Therefore we urge you to link to the glossary whenever you can, using the Glossary macro:

Macro Result Note
{{Glossary("browser")}} browser When a text matches the term to be defined, just use the macro as is (it's case insensitive)
{{Glossary("browser", "Web browser")}} Web browser To display an alternative text, use the second argument to specify that text
{{Glossary("browser", "Web browser", 1)}} Web browser Specify 1 as an optional third argument to display the link as a regular link rather than a subtle hint

Links created with the {{Glossary}} macro always display a tooltip containing the glossary entry's summary paragraph.

使い方のガイドライン

In many cases, it's perfectly safe to use that macro everywhere on MDN. However, there are a few cases you should handle with care:

  • If a term is already linked to another part of MDN, leave it that way and do not use the {{Glossary}} macro.
  • Within an article section, use the {{Glossary}} macro only once for the same term (hint: a section always starts with a title).

ドキュメントのタグと貢献者

 このページの貢献者: piza_suki
 最終更新者: piza_suki,