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

文書をMDNに入れるかどうかについて、主に2つ考慮する点があります:

  • 文書のトピック (何についてのものか?)
  • 文書の性質 (これはどんな種類の文書か?)

Note: Keep in mind that Mozilla's Websites & Communications Terms of Use are in effect when you use or contribute to MDN. Review this document to ensure that you're aware of what can and cannot be posted on Mozilla sites.

MDNに含まれるトピックは?

MDNでは驚くほど色々な種類の中身をカバーしています。つまり、一般に、オープンなWebが直面するテクノロジーである場合、これをMDNにて文書化します。しかし、直接的なものはMDNに含まれなかったり、判断が難しいことも少しあります。この節では、MDNをあなたの文書化のホームとするのに適しているかを理解するのに役立ちます。

これは、我々がカバーしている一部を味見したものです。つまり完全なリストではありませんが、あなたに見解をもたらすでしょう。

オープンな Web 標準とテクノロジー

我々の 文書化についての現在の重点は、オープンウェブテクノロジー — 今日や近い未来にサイトやアプリを作っているWeb開発者によって使用される機能 — です。これはつまり、複数ブラウザで実装され、標準として受け入れられるものや、標準化に向けて前進しているものを意味します。第一の重点箇所は、フロントエンドwebテクノロジーです。バックエンドテクノロジーには、別の文書化の場所があり、MDNはこれにとって変わるつもりはありません。

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

テクノロジーを横断しているが、Web開発に関係するトピックも歓迎されます、例えばこちら:

Note: MDN covers even non-Mozilla technologies if they're exposed to the Web; for example, we have documentation for WebKit-specific CSS properties.

Mozilla 製品

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

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

MDNに含まれないトピックは?

MDN用のトピックとしてふさわしくない例は次の通り:

  • Webに公開されていないテクノロジーだが、Mozilla以外のブラウザに固有のもの
  • WebにもMozilla製品にも関係しないテクノロジー
  • エンドユーザ向けドキュメント。つまりMozilla 製品では、こうした文書はMozilla support siteに入っています。

MDNに含まれる文書の種類は?

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

これらがMDNとしてふさわしくないタイプのドキュメントの例です。

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

MDNに文書化するメリット

もしあなたがあなたが書きたいドキュメントがMDNのコンテンツとして適切かどうかを決定したい場合、また、そのドキュメントを投稿するのにMDNが一番良い場所かどうかを確信していない場合、この記事を読みましょう。ここにはたくさんのMDNにドキュメントを作成するためのメリットが載っています。

たくさんのライターと翻訳者

MDN コミュニティは大きいです。MDNの中身を作成、維持することに参加している人がたくさんいます。ライターとエディターが全ての大陸(南極にはいないかも、それ以外で)にいて、ライターが多数いる価値があります。

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

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

維持

Because of the sheer number of contributors, there's usually someone on hand to watch for problems with your content: from spam control to copy-editing, things can happen around the clock. Here's just a taste of what our team can do:

スパム削除
Spam happens. We deal with it.
文章推敲
You don't have to worry if your writing isn't as clear or precise as you'd like. We'll turn your prose into something other people can read.
スタイルの一貫性
We'll ensure that your content is stylistically consistent not just within itself, but with the other documentation around it.
コンテンツ管理t
Our team will help ensure that the documentation is cross-linked with other relevant materials, that articles are put in the right places, and that menus and other infrastructure is built to make it easy to follow and understand.
サイトとプラットホームの維持
MDN has both an IT team who keep the site up, running, and secure, and a platform development team who maintain and enhance the platform. You won't need to devote your own or additional resources to documentation infrastructure.

他の場所に文書化する場合

MDN以外のどこかに成果を文書化するのを考える理由も少しあります。その理由のいくつかと、デメリットを示します。

計画と手順

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

Github上のプロジェクト

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

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

この事項に困らなかったり、問題ない場合もあります。文書をチーム自身で書いたり維持したりしても構わなかったり、文書の必要性が最低限なコードに関わる場合。

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

Some teams like to have their documentation in the source tree. This is particularly common with project internals and library projects.

This approach has a couple of advantages:

  • It lets the developers document their technology as they code it, helping to ensure that the docs stay up to date with the code.
  • Docs can be subject to the same development and release processes as the code, including versioning.

There are some drawbacks:

  • The MDN docs team can't help you; even if the code is within Mozilla's source repository, the system of reviews and check-ins make it impractical for the docs team to participate.
  • You don't have easy tools for cross-linking with other relevant documentation. Cross-linking provides both context and additional important information to your readers.
  • Your documentation loses discoverability by not being among other documentation.
  • Even if you use conversion tools (like JavaDoc) to create Web-readable documentation, it won't be as attractive as what we can do on MDN.

Still, this can be a viable option (possibly even a good option) for some types of projects, especially small ones or those that aren't expected to get much interest.

^ It's OK to put a limited amount of personal information on your MDN profile page. User profiles should reflect a human being, not a business or organization. A moderate degree of self-promotion is OK, but link-spamming is not. Please do not use your profile to upload personal photos or other irrelevant files.

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

このページの貢献者: wbamberg, Uemmra3, lv7777
最終更新者: wbamberg,