私たちが書くもの

MDN Web Docs には、ウェブ開発者がブラウザーを意識することなくコードを書けるように、ブラウザー中立的な文書を掲載しています。この記事では、特定のトピックやコンテンツの種類が MDN Web Docs に入れられるべきかどうかについての情報を探ります。

編集方針

この節では、 Mozilla MDN のスタッフが MDN Web Docs のコンテンツを管理するために設定したポリシーについて説明します。 MDN Web Docs への協力者はすべて、これらのポリシーを遵守することが期待されます。

関連性

MDN のすべてのコンテンツは、それが現れる技術セクションに関連していなければなりません。スパム(商業広告)およびその他の無関係なコンテンツは、このサイトでは受け付けられません。 Mozilla MDN のスタッフの裁量により、スパムを投稿するユーザーは MDN から追放されることがあります。

リンクされているトピックに関連する商用サイトへの外部リンクは、ケースバイケースで判断されます。ウェブ開発者を支援するうえでのその価値は、リンク先サイトの商業的利益を上回るものでなければなりません。

中立性

MDN Web Docs の記事は中立的な視点を保持し、編集上の偏見なくブラウザーのバリエーションについて報告しなければなりません。任意のブラウザーまたはユーザーエージェントについての論評は容認できません。

標準化

MDN Web Docs で文書化されるウェブ技術は、標準化される予定があり、少なくとも1つのレンダリングエンジンが実装しているものである必要があります。ブラウザー対応状況の違いは、記事のブラウザーの互換性の節に記載されています。

コンテンツの提案

MDN Web Docs にコンテンツを提案したい場合は、投稿する前に必ずこのページを読んで、提案する内容が適切かどうかを確認してください。

新しいリファレンスページやガイドについては、新しい issue で、提案する内容とその理由を説明するディスカッションを開いてください(できるだけ明確にしてください)。

コンテンツの新しいセクションを含む大規模なプロジェクトを提案する場合は、掲載基準ページを参照し、申請プロセスについても概説してください。

どのようなトピックが MDN Web Docs に載るのか

一般的には、オープンなウェブ向きの技術であれば、MDN 上で文書化します。これは、現在および近い将来にサイトやアプリケーションを作成するウェブ開発者が使用できる機能を意味します。

複数のブラウザーで実装されていて、標準として受け入れられているか、標準化に向けて進んでいるものであれば、そうですね。もしそれがまだ非常に実験的で、複数のブラウザーで実装されておらず、変更される可能性がある場合、それでも載せるのに適してはいますが、ライターのチームが取り組むべき優先事項とは見なされないかもしれません。

つまり、MDN Web Docs で文書化されるウェブ技術は、次のような条件をすべて満たすものでなければなりません。

  • 標準化路線に乗っていること。
  • 信頼できる標準化団体から発行された仕様書で仕様化されていること。
  • 少なくとも 1 つのレンダリングエンジンに実装されていること。
  • 安定版のブラウザーでリリースされていること。

主に次のようなフロントエンドのウェブ技術について書くことに焦点を当てています。

また、SVG, XML, WebAssembly, アクセシビリティなど、より幅広いトピックについても文書化しています。さらに、これらの技術に関する豊富な学習ガイド用語集を提供しています。

メモ: バックエンドテクノロジーには、別の文書化の場所があり、 MDN Web Docs はこれにとって代わるつもりはありませんが、いくつかの例外はあります

MDN Web Docs のすべてのコンテンツは、それが掲載されている技術分野に関連したものでなければなりません。投稿者は、書き方やコードサンプルなどについて、この MDN 執筆ガイドライン に従うことが期待されています。

MDN Web Docs に技術を文書化できるかどうかの基準についての詳細は、掲載基準ページを参照してください。

新しい技術を文書化するとき

MDN Web Docs で、私たちは常に新しいウェブ標準技術を適切に文書化することを検討しています。 私たちは、開発者が必要なときにすぐに新機能を知ることができるように十分に早く文書を公開することと、文書が常に更新されたり急速に削除されたりする必要がないよう、技術が成熟し安定した状態まで十分に待ってから公開することのバランスを取ろうと努めています。

一般的に、私たちが新しい技術の文書化を検討する時期について、「その機能が標準化の流れにあって、どこかに実装されたとき」と定義しています。

私たちは、次のような場合、新しい技術を文書化することを考えます。

  • 信頼できる標準化団体(W3C、WHATWG、Khronos、IETF など)の下で発行された仕様書に明記され、妥当なレベルの安定性に達している(たとえば、W3C の作業草案または勧告候補、あるいは仕様に対して申し立てられた問題の流れから判断してかなり安定していると思われる場合など)。
  • 少なくとも 1 つのブラウザーで一貫して実装されており、他のブラウザー開発者が関心を示している(アクティブなチケットや "intent to implement" プロセスが有効であるなど)。

私たちは、次のような場合、新しい技術の文書化は行いません。

  • 仕様書がない、または仕様が大まかなもので、今後変更される可能性がある場合。
  • 現在、その技術を搭載しているブラウザーが1つまたはゼロであり、対応していないブラウザーがその技術の実装に関心を示す気配がない。これは、ブラウザーのバグトラッカーやメーリングリストなどを見て、そのブラウザーの開発を行っている技術者に依頼することで判断することができます。
  • ウェブに公開されている技術ではない、あるいは完全に独占的な技術である。
  • すでに非推奨になっている、または類似の機能に取って代わられる兆しがある。

MDN Web Docs に掲載しない主題

一般的に、オープンウェブの標準でないものは MDN Web Docs にふさわしくありません。スパム(商業広告)およびその他の無関係なコンテンツは、決してサイトに受け入れられません。スパムを投稿しようとする投稿者は、Mozilla MDN スタッフの判断により、MDN から追放される可能性があります。

MDN Web Docs に不適切なトピックの例としては、以下のようなものが挙げられます。

  • ウェブに公開されない、あるブラウザーに特化した技術。
  • ウェブに関連しない技術。
  • エンドユーザー向けの文書化。例えば Mozilla 製品の場合、そのような文書は Mozilla サポートサイト に属します。
  • 自己リンクや自己宣伝のための外部リンク。外部リンクを追加する前に、執筆スタイルガイドにあるガイドラインを確認してみてください。

文書を削除する場合

MDN Web Docs からページが削除されるのは、有用な情報が含まれていない場合や 十分に古い情報である場合、あるいは残しておくと誤解を招く可能性がある点で間違っている場合です。

次の例は、ページやコンテンツが削除される可能性がある状況を記述したものです。

  • すべてのブラウザーに搭載されず、後に取り下げられた機能(通常は接頭辞付きの機能などの実験的な機能)に関する情報を含んでいる記事。
  • ブラウザーに搭載される前に仕様書から削除された機能を記述したリファレンスページ。
  • 後に悪しき慣習であることが示され、より優れた技術に取って代わられた技術を扱っている記事。
  • 後に他のより良い品質の情報に置き換えられた情報が含まれている記事。
  • MDN Web Docs には不適切なコンテンツを含む記事。
  • MDN Web Docs のあるセクションがオープンウェブ技術にフォーカスされておらず、メンテナンスに負担がかかっている場合。

文書の削除方法については、ページの作成、移動、削除のガイドを参照してください。

MDN Web Docs に掲載する文書の種類

一般的に、私たちの文書化は次のようなカテゴリーに分けられます。

  • リファレンス
  • ガイド
  • 用語集
  • 学習/チュートリアル

一般に、 MDN Web Docs はプロダクトのドキュメントであり、プロジェクトプロセスのドキュメントではありません。そのため、もしドキュメントが「どのように使うか」や「どのように動作するか」(「どの」とは前述した特定のカテゴリーのことです)なら MDN Web Docs に掲載しましょう。

文書が「誰が開発したか」や「開発プランについて」などは MDN Web Docs にふさわしくありません。

MDN Web Docs に掲載するのにふさわしくない種類の文書の例をいくつか挙げます。

  • 計画書
  • 設計書
  • プロジェクト提案書
  • 仕様書や標準
  • プロモーション素材、広告、個人情報