これは MDN Web Docs に掲載するものですか?

この記事では、ある主題やコンテンツの種類を MDN Web Docs に載せるべきかどうかを決定する方法について説明します。また、詳細ではありませんが、コンテンツを配置する可能性のある他の場所についても検討します。

問い

何らかの文書をまとめる準備をしている場合、その情報を MDN Web Docs に載せるどうか考えるかもしれません。加えて、ソースコード内の文書を維持したり、その文書を Mozilla wiki や、git リポジトリー内の readme ファイルに置いたりすることを検討しているかもしれません。この記事の目的は、あなたのコンテンツが、これらのオプションのどれにふさわしいのかを決めるのに役立つことです。

文書を MDN に載せるかどうかについて、主に 2 つ考慮する点があります。

  • 文書の主題 (何についてのものか)
  • 文書の性質 (これはどんな種類の文書か)

MDN への寄稿は、すべて特定のオープンソースライセンスに該当することに注意してください。これは MDN についてページに詳細に記されています

: MDN Web Docs を利用したり、投稿したりする際には、Mozilla のウェブサイトおよびコミュニケーション利用規約が適用されることに注意してください。この文書を確認して、Mozilla のサイトで投稿できること、できないことを確認してください。

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

一般的には、オープンなウェブ向きの技術であれば、MDN 上で文書化します。これは、現在および近い将来にサイトやアプリケーションを作成するウェブ開発者が使用できる機能を意味します。複数のブラウザーで実装されていて、標準として受け入れられているか、標準化に向けて進んでいるものであれば、そうですね。もしそれがまだ非常に実験的で、複数のブラウザーで実装されておらず、変更される可能性がある場合、それでも載せるのに適してはいますが、ライターのチームが取り組むべき優先事項とは見なされないかもしれません。

主にフロントエンドのウェブ技術に重点を置いています。

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

また、複数の技術にまたがるが、以下のようなウェブ開発に関連したトピックも歓迎します。

注: MDN は、ウェブに公開されていて、特に一般的に使われている場合には、一部の標準外の機能をカバーしています。例えば、WebKit 固有の CSS プロパティのドキュメントがあります。MDN は、ウェブ開発者にとって十分に有用であると考えられる場合には、ウェブ標準以外の技術もカバーしています。ウェブ関連技術のセクションを参照してください。

MDN Web Docs に掲載しない主題

一般医、オープンなウェブ標準ではないものはすべて、MDN に掲載するものではありません。以下にもっと具体的に示します。

Mozilla 製品

このカテゴリーの文書には、 Mozilla 製品に対して開発者として作業する方法と、これらのオープンソースプロジェクトに貢献する方法との、両方があります。

MDN には Mozilla 製品の文書が大量にありますが、新規コンテンツ開発の重点はオープンウェブに置いています。MDN に Mozilla 製品の文書を新規作成することは推奨されません。Mozilla 製品 (やそうなるかもしれない製品) の作業を進めている場合は、MDN スタッフチームのメンバーに話して、その製品の文書化の道を議論してください。また、下記の他の場所に文書化する場合も見てください。

それ以外

その他の MDN Web Docs のトピックとして適切ではないものの例です。

  • ウェブに公開されていない技術で、Mozilla 以外のブラウザーに固有のもの
  • ウェブにも Mozilla 製品にも関係しない技術
  • エンドユーザー向け文書。Mozilla 製品では、こうした文書は Mozilla サポートサイトに載っています。

MDN に掲載する文書の種類

一般に、MDN はプロダクトのドキュメントであり、プロジェクトプロセスのドキュメントではありません (MDN 自体についてを除く)。そのため、もしドキュメントが「どのように使うか」や「どのように動作するか」 (「どの」とは下記で記述されている特定のカテゴリのことです) なら MDN に掲載しましょう。しかし、「誰が開発したか」や「開発プランについて」などは MDN にふさわしくありません。Mozilla 傘下で開発されているものの場合は Mozilla project wiki に掲載するといいでしょう。

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

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

MDN で文書化する利点

もし書きたいドキュメントの内容や種類が MDN に適していると判断したとしても、MDN が最適な場所かどうか迷っているのであれば、読んでみてください。MDN でドキュメントを作成する利点はたくさんあります。

たくさんの執筆者と翻訳者

MDN コミュニティは巨大です。MDN のコンテンツの作成や保守に参加している人がたくさんいます。すべての大陸に (南極ではないかもしれませんが、それ以外には) 執筆者や編集者がいて、執筆者の数の多さには価値があります。

  • 雇用している本職の執筆者がいて、できるだけコンテンツをより良いものにするミッションが与えられています。
  • ボランティアの中心となるコミュニティがあり、あなたを手助けするかなりの量のコンテンツに協力しています。
  • MDN チームは、あなたの文書化プロジェクトに十分人を配置することを保証すべく、一緒に作業してくれます。
  • 広大な MDN コミュニティは大量に貢献します。誤字の修正からコンテンツの編集レビューまで、助けてくれます。
  • MDN Web Docs チャットルームMatrix にあり、ライターコミュニティに話してアドバイスを得る場や、コンテンツ作成や維持を助ける人を採用する場を提供します。
  • 全世界に協力者がいるため、問題を見ていたり直したりする人がいつも周りにいます。
  • ボランティアコミュニティには、多くの言語へ翻訳する人がいて、ドキュメントのローカライズを手伝っています。

あなたの開発チームが、文書作成に全責任を負うことを望みますか?その場合はおそらく他の場所で文書を維持するべきでしょう。

保守

投稿者の数が非常に多いため、通常、コンテンツに問題がないかどうかを監視するために、誰かが常駐していま。スパム対策からコピー編集まで、24時間体制で対応しています。ここでは、私たちのチームができることのほんの一例をご紹介します。

スパム削除
スパムは発生します。それに対処します。
文章の推敲
文章が思うようにはっきりしていなくても、正確でなくても心配する必要はありません。散文を、他の人が読めるような文章に仕上げます。
スタイルの一貫性
コンテンツが、それ自体だけでなく、その周りにある他のドキュメントとスタイル的に一貫していることを確認します。
コンテンツ管理
私たちのチームは、ドキュメントが他の関連資料とクロスリンクされ、記事が適切な場所に配置され、メニューやその他のインフラストラクチャが構築されているかどうかを確認し、フォローしやすく、理解しやすいように支援します。
サイトとプラットホームの維持
MDN には、サイトの稼働、運営、安全性を維持するITチームと、コンテンツが表示されるプラットフォームを維持、強化するプラットフォーム開発チームの両方があります。ドキュメントのインフラに自分のリソースや追加のリソースを割く必要はありません。

他の場所で文書化した場合

MDN 以外のどこかで成果を文書化するのを考える理由も少しあります。その理由のいくつかと、利点や欠点をそれぞれ示します。

計画書や手順書

計画書や手順書や提案書は、決して MDN に載せてはいけません。これはとても単純なことです。製品が Mozilla のものなら、Mozilla project wiki に置くことができます。

Github 上のプロジェクト

Mozilla の製品のいくつかは Github にホストされていて、Github では wiki 的な文書化システムが提供されています。文書をそこに作成するチームもあります。文書を作成するには確実にフェアで便利ですが、次に注意してください。

  • MDN はたぶんあなたを手助けできません。一般的に我々は MDN 以外の文書作業には加わりしません。例外はあるものの、まれです。
  • あなたの文書と、関連する他の素材をクロスリンクするのは、困難だったり、不可能になるかもしれません。
  • コンテンツが他の文書と一貫したスタイルが持てなくなります。
  • 他の (ウェブや Mozilla の) 文書の外にあるため、文書の発見しやすさが失われます。

もちろん、これらのことが困ることではなかったり、問題にならなかったりする可能性もあります。チームによっては、自分たちでドキュメントを書いたりメンテナンスしたりすることを気にしない、あるいは最低限のドキュメントの必要性があるコードに取り組んでいるチームもあります。

ソース内に文書を置きたい場合

一部のチームでは、ドキュメントをソースツリーに配置したがることがあります。これは特にプロジェクトの内部やライブラリプロジェクトでよく見られます。

このアプローチにはいくつかの利点があります。

  • これにより、開発者が技術をコーディングしながらドキュメントを作成することができ、ドキュメントがコードを常に最新の状態に保つことができるようになります。
  • ドキュメントは、バージョン管理を含め、コードと同じ開発とリリースのプロセスに従うことができます。

欠点もあります。

  • MDN Web Docs チームはあなたを助けることができません。コードが Mozilla のソースリポジトリー内にあっても、レビューとチェックインのシステムにより、docs チームが参加することは現実的ではありません。
  • 他の関連文書とのクロスリンクを行うための簡単なツールがありません。クロスリンクは、読者にコンテキストと追加の重要な情報の両方を提供します。
  • ドキュメントが、他のドキュメントの中に存在しないことで発見可能性を失います。
  • 変換ツール (JavaDoc など) を使ってウェブで読めるドキュメントを作っても、MDN Web Docs でできるものほど魅力的なものにはならないでしょう。

それでも、これはいくつかの種類のプロジェクト、特に小さなものや、あまり興味を持たれることが期待されていないものに対しては、実行可能な選択肢 (良い選択肢である可能性もあります) になるでしょう。

自分のプロフィールについて

MDN のプロフィールページには、限られた個人情報を掲載しても構いません。ユーザーのプロフィールは、企業や組織ではなく、人間を反映したものであるべきです。適度な自己 PR は OK ですが、リンクスパムは不可です。個人的な写真やその他の無関係なファイルをアップロードするためにプロフィールを使用しないでください。