適切にタグづけするには
記事のタグは、ユーザーが役立つコンテンツに触れるための重要な方法です。コンテンツを分類するために、それぞれのページは通常いくつかのタグを持っています。このページでは、読者が情報を見つけやすく、また私たち自身が整理しやすくするために、ページにタグ付けする最良の方法を説明します。
以下に説明するように、タグを適切に使ってください。そうしないと、自動化ツールからコンテンツ一覧や、ランディングページや、記事のクロスリンクを正しく生成できません。
警告: 翻訳者へのメモ: このページに掲載されているタグを翻訳しないでください。これらは、特定のサイト管理作業や自動データ処理など、特定の目的のために使用されており、翻訳することでこれらのプロセスを壊すことになります。
MDN のタグの用途
MDN ではタグがいくつかの用途で使われています。
- 文書の分類
-
どの種類の文書か。リファレンスであるか。チュートリアルであるか。ランディングページであるか。訪問者がこれらのタグを使って検索の絞り込みをすることができるので、本当に重要です。
- トピックの識別
-
何に関する記事なのか。 API についてなのか。 DOM か、 グラフィックか。また、これらは検索の絞り込みに使えるので重要です。
- API の識別
-
API について記述するリファレンスページは、 API についての要素(どのインターフェイスの一部なのか、そのページで扱うプロパティもしくはメソッド)を特定することで分類されます。
- 技術の状態
-
その技術の状態は何か。標準外 (non-standard) か、非推奨 (deprecated) か、実験的 (experimental) か。
- スキルレベル
-
チュートリアルとガイド向け、どれだけ記事で扱う題材が進んでいるのか?
- 文書メタデータ
-
物書きのコミュニティは、特定の作業が必要となるページの情報を追跡するのにタグを使います。
タグの種類のガイド
タグの種類と取りうる値の簡単なガイドをします。
文書のカテゴリー
記事に対してこれらのカテゴリーの中の1つをタグ付けすれば、自動化ツールがランディングページや目次などをより正確に作成するのに役立ちます。新しい検索システムでは、これらの用語を使って、訪問者が望むリファレンスやガイド情報の場所を位置付けることができます。
下記のカテゴリー名を標準的なタグ付け用語として使っています。
Intro
-
この記事はあるトピックについての入門的な素材を提供します。できれば、それぞれの技術分野に Intro は1つだけであるべきです。
Reference
-
この記事は API、要素、属性、プロパティ、などに関するリファレンスの資料を含んでいます。
Landing
-
このページはランディングページです。
Guide
-
この記事は手順書やガイドのページです。
Example
-
この記事はコード例のページや、コード例を含むページです(つまり、 1 行の「構文の例」ではなく、実際に利用できるコードの断片です)。
トピック
記事のトピックの範囲を識別することで、よりよい検索結果を作り出すのに役立ちます(ランディングページとナビゲーションも同様)。
新しいトピック分野を指定する際にはいくらか自由度がありますが、 API や技術の名前に制限しようとしています。以下のような有用な例があります。
HTML
CSS
JavaScript
("S" は大文字です!)Document
DOM
API
個々の API の概要、インターフェイス、メソッド、プロパティMethod
API の個々のメソッドProperty
API の個々のプロパティGraphics
SVG
WebGL
Tools
Web
Element
Extensions
およびWebExtensions
ウェブ拡張機能の文書。
一般的に、トピックを識別するタグは、関連する多数のページがあるインターフェイス(例えば様々なプロパティやメソッドのページがある Node など)の名前や、技術全体の種類の名前であるべきです。例えば、 WebGL についてのページは Graphics
と WebGL
でタグ付けしたくなるでしょうが、 <canvas>
に関するページは HTML
, Element
, Canvas
, Graphics
になるでしょう。
Mozilla 固有のコンテンツ
これらのタグは、 Mozilla 固有のコンテンツでのみ使われます。
Mozilla
Firefox
Gecko
XUL
XPCOM
API の識別
API リファレンスの中では、それぞれの記事が API のどの部分に対応するのかを識別できるようにしてください。
Interface
-
インターフェイスに関する主要な記事にはこのタグをつけてください。例:
RTCPeerConnection
Constructor
-
それぞれのインターフェイスには、 "Constructor" とタグ付けされたページが最大1ページある場合があります。これはインターフェイスのコンストラクターです。ページは
RTCPeerConnection.RTCPeerConnection()
のように、インターフェイスと同じ名前にしてください。. Property
-
インターフェイス中の特定のプロパティを説明する記事には、すべてこのタグが必要です。例えば、
RTCPeerConnection.connectionState
(en-US) を参照してください。 Method
-
インターフェイスのメソッドについて記述している記事には、全てこのタグが必要です。例えば、
RTCPeerConnection.createOffer()
(en-US) を参照してください。
加えて、リファレンスページはインターフェイス、プロパティ、メソッドの名前でタグ付けする必要があります。例:
RTCPeerConnection
インターフェイス-
RTCPeerConnection
を、他の関連するタグ (Interface
,WebRTC
,WebRTC API
,API
,Reference
など) と共にタグ付けしてください。 RTCPeerConnection.createOffer()
(en-US) メソッド-
RTCPeerConnection
とcreateOffer
(注: タグ名に括弧を含めないでください) を、他の関連するタグ、Method
,WebRTC
,WebRTC API
,API
,Reference
などと共にタグ付けしてください。関連性に応じてOffer
やSDP
などの関連するタグでタグ付けすることも検討してください。 RTCPeerConnection.iceConnectionState
(en-US) プロパティ-
RTCPeerConnection
とiceConnectionState
を、他の関連するタグ、Property
,WebRTC
,WebRTC API
,API
,Reference
などと共にタグ付けしてください。ICE
もタグ付けすることを検討してください。
技術の状態
読者が技術の利用可能性を理解しやすくするため、技術の仕様の状態に関するラベルをページに付与するためにタグ付けします。これは、仕様がどのようなものであるか、技術が仕様プロセスにどれだけ届いているか (それは仕様表の役割) を実際に説明するほど詳細ではありませんが、読者が記事に書かれた技術を利用することが良いことかどうかを一目で判断するのに役立ちます。
これらのタグとして有効な値は以下の通りです。
Read-only
-
読み取り専用のプロパティや属性を記すリファレンスページにこのタグを適用してください。
Non-standard
-
このページで説明している技術や API が、実装しているブラウザーで安定しているかどうかにかかわらず、標準化されていないことを示します (安定していない場合は Experimental")}} を使用してください)。このタグを使用しない場合は、読者は技術が標準化されていると仮定します。ページ上の互換性テーブルで、どのブラウザーがこの技術や API に対応しているかを明確にしてください。
Deprecated
-
このページで述べられている技術や API は推奨されなくなりました。将来的に削除される可能性があり、また互換性のためにのみ保持される可能性があります。この機能の使用は避けてください。
Experimental
-
この技術は標準化されておらず、標準化されるかどうかわからない実験的な技術や API です。これが実装されるかどうかは、ブラウザーのエンジンの変更 (ふつうは1回) に依存します。その技術が (ドラフト版も含め) 仕様に加えられていない場合は、 Non-standard もタグ付けしてください。
Needs Privileges
-
この API は、コードが実行される端末へのアクセス権限を要求します。
Certified Only
-
この API は認証されたコードのみで動作します。
これらでタグ付けしたとしても、記事の互換性テーブルを省略してよいことにはなりません。互換性テーブルは常にあるべきです。
スキルレベル
スキルレベルの種類のタグは、ガイドやチュートリアル (つまり Guide
とタグ付けされたページ) にのみ使用し、ユーザーがその技術にどれほど慣れ親しんでいるかに基づいてチュートリアルを選択する手助けになります。これには3つの値があります。
Beginner
-
その技術を使ったことがなかったり、ちょっと触れただけの読者に紹介するために作られた記事です。
Intermediate
-
その技術を使い始めているものの、エキスパートにはなっていない人を対象とした記事。
Advanced
-
技術や読者の可能性を伸ばすための記事。
文書メタデータ
執筆コミュニティが、特定の種類の作業を必要とする記事にタグを使ってラベル付けをしています。よく使用しているものの一覧は以下の通りです。
Draft
-
記事が完全ではなく、少なくとも理論的には積極的に更新されています (ただし、忘れられている可能性もあります)。潜在的なコンテンツの衝突を避けるため、変更する前に最新の投稿者に確認してください。
NeedsCompatTable
-
この記事はブラウザー間の機能の互換性を記述する表が必要です。ブラウザーの互換性に協力する際のガイドはこちらを参照してください。
NeedsContent
-
記事はスタブであるか、情報が不足しているかです。このタグは、誰かが内容を見直して詳細を追加したり、記事を書き終えたりするべきであることを意味します。
NeedsExample
-
記事には、その記事の要点を説明するために役立つ例が必要です。これらの例では、コード例スタイルを利用してください。
NeedsLiveSamples
-
この記事には、ライブサンプルシステムを使用するように更新する必要がある例があります。
NeedsMarkupWork
-
この記事は、ページのマークアップを改善する必要があります (ふつうはページの内容のほとんどまたはすべてが
<p>
タグから成るため)。 NeedsSpecTable
-
この記事には、この機能がどの仕様書で定義されたかを示す一覧表が必要です。
NeedsUpdate
-
このコンテンツが古くなっており、更新する必要があります。
l10n:exclude
-
このコンテンツはローカライズする価値がなく、ローカライズ状況ページに表示されません。
l10n:priority
-
このコンテンツは重要であり、 MDN の翻訳者にとって重要だとマークするべきです。ローカライズ状況ページの優先度の高い記事の表に表示されます。
すべて一緒に設定する
それぞれのページについて、いくつかの異なる種類のタグを指定することになるでしょう、例えば
- 初心者のための WebGL に関するチュートリアル
-
WebGL, Graphics, Guide, Beginner
<canvas>
のリファレンスページ-
Canvas, HTML, Element, Graphics, Reference
- Firefox 開発者ツールのランディングページ
-
Tools, Firefox, Landing
修正可能なタグ付けの問題
修正できるタグの問題が、次のように数種類あります。
- タグなし
-
一般的に記事には少なくとも "カテゴリー" タグと "トピック" タグが必要です。常にその他のタグもふさわしく、しかし最低限のタグがあるように手助けしていただけると、あなたは文書化のヒーローになります!
- タグがタグ付けの規約に従っていない
-
タグがこのページの標準にそっていないページは修正してください。
なお、たまにローカライズされたタグ (Référence
のような) を英語ページ内に見かけることがあります。これは Kuma のバグのせいで、このバグのためにタグを消してもまた出てきます。このバグは修正済みで、残っているローカライズされたタグは指定されたら片付けられます。
- 正しくないタグ
-
HTML についての記事を探していてそれが "JavaScript" とタグ付けられていたら、多分間違いです! 同様に記事が Mozilla 内部のことを書いていて "Web" タグがあったら、これも多分間違いです。これらのタグを削除して、適切なタグが欠けていたら追加します。スペルミスのタグ (例 "Javascript" は、タグが大文字小文字を区別しないのでマッチしますが、間抜けになるのはやめましょう!)も訂正してください。
- タグの欠落
-
記事のタグがあるけど必要なすべてはない場合、気軽に追加してください。例えば、 JavaScript リファレンスページが "JavaScript" だけで (正しく) タグ付けられている場合、同じく "Reference" とタグ付けするよう誘われています!
- タグのスパム
-
この陰湿な獣は、すべての中で最も不愉快なタグの問題です: あるウェブ害虫が、その糞をページタグに堆積させています (例えば、"Free warez!" や "Hey I was browsing your site and wanted to ask you if you could help me solve this problem I'm having with Flash crashing all the time" など)。これらは直ちに削除する必要があります。これらは醜いし、長く残ってしまうと管理不能となり、 SEO にも悪影響です。