MDN Web Docs の掲載基準

MDN Web Docs の使命は、信頼できる標準化団体によって公開された仕様書にあり、少なくとも一つの安定したブラウザーで対応しているウェブ標準技術を文書化することです。これらの基準は、ウェブ業界全体による十分な関心、安定性、そして「実装する意図」を示すものです。したがって、これらの技術は、私たちが文書化に時間と労力を費やしても問題ない技術だと考えています。これより早いと、ウェブ技術や機能は、関心の低さから取り消される可能性があったり、とても不安定で大きく変化する可能性があったりして、不必要に多くの書き換えが必要になります（私たちは可能な限りこれを避けようとしています）。

ウェブ以外の標準技術とは、上にまとめた私たちの基準に従わない技術のことです。通常、私たちは MDN Web Docs の文書としてそれらを検討することはありません。

私たちのミッション・ステートメントは、「オープンなウェブ上でプロジェクトを簡単に構築するために必要な情報を開発者に提供すること」です。これは、たとえそれがオープンなウェブ標準でなくとも、ウェブ開発者にとって有用な技術を文書化し、標準化トラックなどに載せることを検討すべきであると示唆しています。

もしウェブ以外の標準的な技術を MDN Web Docs に含めることを検討したいのであれば、以下の基準に一致することを確認する必要があります。

MDN Web Docs で 文書化 を検討するためには、ここに記述した基準を満たす必要があります。

MDN Web Docs では、私たちはオープンな技術を支援しています。私たちは、単一の組織によって管理され、関心を持つあらゆる人に開放されておらず、複数のプラットフォームやシステム間で相互運用できないような、閉じた技術のエコシステムを支持しません。私たちは、技術はオープンに作成されることで、誰にとってもよりよく動作すると信じています。

私たちの中心的な任務はウェブ標準技術です。ウェブに関連のない技術、あるいはウェブ開発者の関心を引くことのない技術の文書化を始めても、この点には意味がありません。

私たちは、業界からの関心や採用の兆しがない技術を文書化することに時間を費やしたくありません。その技術の文書化を始めるには時期尚早というだけで、将来的には MDN Web Docs で文書化することを検討してもよいかもしれません。

この点とも関連しますが、ライフサイクルの後半にあり、すでに関心が薄れつつある技術の文書化に時間を費やしたくないという思いもあります。

ウェブ標準ではないものの、ウェブ技術の上に構築され、ウェブ業界でとても人気のあるライブラリーやフレームワークがたくさん存在しています。一般的に、これらはすべてすでに確立された文書化されたリソースがあるため、私たちはこれらの文書を一切作成していません。人気のあるフレームワークの公式リソースと競合するのは愚かなことです。そうすることは時間の無駄であり、おそらくその技術を学ぼうとする開発者を混乱させる結果になるでしょう。

MDN Web Docs のチームは、オープンウェブプラットフォームの文書化に集中しています。この分野の技術を MDN Web Docs での文書化の対象として検討したい場合、文書を書き、完成後もそれを維持することをいとわないコミュニティが集まっている必要があります。私たちのチームは、そのような場合、編集やフィードバックなどの指導を喜んで提供しますが、それ以上のリソースは持ち合わせていません。

MDN Web Docs で文書化するのに適していると思われる技術があれば、 GitHub community の discussions で議論を始めることができます。この節では、提案に記載する内容を記述します。

技術は、案件ごとに MDN Web Docs への掲載が検討されます。検討のためには、 "Proposal for documenting a new technology on MDN Web Docs" というタイトルの提案書（英語）を提出する必要があります。提案書には、次のような情報が必要です。

• 技術、その中核となる目的/用途、ターゲットとなる開発者層。
• この技術について、どのような業界やコミュニティの話題があるのか。
  • 多くのウェブ開発者が使用しているのか。業界ではどのような採用が進んでいるのか。
  • 多くのウェブ開発者がこの情報を欲しがったり、必要としたりしているのか。
  • この情報のターゲット層はどの程度か。補助的な統計データがあれば役立ちます。
• その技術は、ウェブのコア技術や ブラウザーとどのように関連しているのか。役立つ詳細は以下の通りです。
  • HTML と CSS を使用するが、一般的にウェブに出力しないのか。
  • ポリフィルでウェブブラウザーが対応しているか。
• その技術をカバーする、既に利用できるドキュメントやリソースは何か。
• MDN Web Docs に追加する文書はどれくらいの規模か？
  • 要素/メソッド/属性などのガイド、チュートリアル、参照ページなどの予定数を列挙してください。
  • 大まかな目次を提供してください。
  • この資料には、基本的な文書化ページを超える、どのような「高度な」機能が必要だと考えられるか。埋め込み動画、インタラクティブなコードサンプルなどを入れることを想定しているか。
• 誰が文書化するのか？彼らは誰で、なぜその仕事にふさわしいのか。
• 文書の管理はどうするのか。

この段階で何百ページもの詳細な情報を提供する必要はありません（むしろ、提供しない方が良いでしょう）。この点については、それぞれ数段落程度で十分です。

提案書に記載された技術や提出された情報を検討し、次のいずれかの回答で対応します。

• No: MDN Web Docs で文書化される基準を満たしているとは思えません。
• Maybe: MDN Web Docsで文書化するのに適しているかどうかわからないため、さらにいくつかの質問をさせてください。
• Yes: MDN Web Docs に載せるのが適切だと考えています。

その技術が良い候補であれば、文書化に向けてチームが支援します。

あなたの選んだ技術が MDN Web Docs の文書化対象として認められたら、次のステップに進みます。

MDN Web Docs で新しい技術を文書化するプロジェクトを成功させるために、次のものを所有していることが必要です。

• 専用チーム
• プロジェクト計画とロードマップ
• 執筆ガイドラインや標準
• 直感的な文書化構造
• メンテナンス計画

最初の文書を作成するだけでなく、将来的に必要な更新を行うための保守を行う専門チームがあることを確認してください。

どのくらいの作業量があるのか、そのために何人必要なのか、考えてみてください。

• 大きなプロジェクトであれば、執筆者が数名いて、作業が技術的に正確かどうかをチェックする技術レビュアー、言葉をきれいにするコピーエディター、サンプルコードを書く人などがいると、より効果的でしょう。
• 小規模なプロジェクトでは、複数の役割を担う人が 1 人か 2 人しかいないかもしれません。しかし、うまくいくのであれば、どのようにチームを構築してもかまいません。

MDN Web Docs チームのメンバーが、あなたのプロジェクトに割り当てられ、 MDN Web Docs 側でガイダンスを提供します。

MDN Web Docs のチームメンバーと連携できるチームリーダーを 1 人（または 2 人）任命してください。

MDN Web Docs の担当者は、あなたのチームの全員に GitHub 上の MDN の組織で作業するために必要なパーミッションを返すのを手伝います。

プロジェクトの計画を作成する - タスク、完成予定日、進捗を確認するためのマイルストーンなどを作成しましょう。

プロジェクトが大規模な場合は、チームメンバーの一人をプロジェクトマネージャーとして任命することを検討すべきです。また、公開してもよい最小限の文書化 (minimum viable product)を包含する最初のリリースのためのサブプロジェクト計画を書くことも検討すべきです。次の追加でそれをフォローアップすることができます。

文書化プロジェクトが小規模であっても、何ができて何ができていないのか、文書の各属がどの段階にあるのか（例えば、未着手、進行中、草案を書いた、レビュー済み、完了）、誰が何の作業をしているのかを記録しておくことが必要でしょう。

このガイドラインは、MDN Web Docs で文書をどのように書くことが期待されるかを述べたものです。

もしあなたが書いている文書に追加のガイドラインがある場合は、このガイドを追加し、最新の状態に保つことを期待します。

標準という意味では、あなたの文書が MDN Web Docs に残るためには、妥当なレベルの文章の質を維持することが期待されます。 MDN Web Docs の担当者は、何が期待されているのかを明確にするために、一緒に作業します。

提案書提出のプロセスを経たのであれば、この技術のために何を書くかという大まかなアウトラインは既に保有しているはずです。この点については、文書階層をどうするか、すべての文書をどこに配置し、リンクさせるかを考え、サイト構成計画に落とし込む必要があります。

プロジェクトごとに異なりますが、おおよそ次のようなものをお勧めします。

ランディングページ
|
------リファレンス
      |
      --------要素
      |
      --------メソッド
      |
      --------その他の種類のリファレンスページ
|
------ガイド/チュートリアル
|
------例

プロジェクトで使用する各ページの種類には、他の人が構造をコピーできるようなページテンプレートがあることが望ましいです。これらは早い段階で決めておくとよいでしょう。

ページの種類の節を参照してください。追加する必要がある場合は、 MDN Web Docs の担当者と連絡を取ってください。

この技術の文書は、MDN Web Docs に残るように整備する必要があります。

• MDN Web Docs のコンテンツとファイルは、 GitHub に格納されます。他の人があなたの技術の文書化に変更を加えた場合、あなたのチームのメンバーがその変更を確認し、コンテンツがまだ良いものであることを確認する必要があります。 GitHub の通知機能により、オープンなプルリクエスト (PR) を追跡することができます。
• 技術に変更があり、文書の更新が必要になった場合、あなたのチームは、元の文書と同じ基準を維持しながら、適切に更新を行う必要があります。

6 ヶ月間積極的な変化が見られず、文書化が次のような状態であると思われる場合。

• 古くなった、または保守されていない
• 未完成のまま停滞している
• 低品質
• 時代遅れになりつつある

この場合、この技術の文書は死んだとみなされます。あなたのチームと MDN Web Docs チームの代表が話し合った後、その文書は削除されます。

質の悪い、不完全な、あるいは時代遅れの文書でサイトを埋め尽くすわけにはいかないので、このような問題には厳しく対応する必要があることをご理解いただければと思います。