ジャンプ先:

この記事では MDN で使用されている慣習や定義、特に文書化する際に人によっては忘れがちなものを紹介します。

定義

非推奨と廃止

非推奨廃止は技術や仕様書によく使われている言葉ですが、どのような意味でしょうか?

非推奨 (Deprecated)
MDN において非推奨 の用語は、もう推奨されないものの、まだ実装されており動作する可能性がある API や技術を示すために使用されます。最近では、 browser-compat-data プロジェクトの中で使用される定義を、「その機能はもう推奨されません。将来は削除されるか、互換性のためだけに温存される可能性があります。この機能を使用することは避けてください。」と更新しました。
廃止 (Obsolete)
MDN において廃止 の用語は、もう推奨されないだけでなく、ブラウザーでももう実装されていない API や技術を示すために使用されます。しかし、これは混乱しやすもののです。 — 非推奨に似ており、区別することがさほど役立たない (こちらも本番サイトでは使用するべきではない) ものです。従って、私たちはこれを使用するのをやめ、使用されている記述を削除するか、非推奨に置き換えるかしてください。

実験的

実験的 (Experimental) は、聞いた場所や読んだ場所の文脈によって意味が異なる可能性があります。 MDN においてある技術が実験的と記述されている場合、その技術は生まれたばかりで未熟であり、現在ウェブプラットフォームへの追加手続の途中の (または追加が検討されている) 段階であることを意味します。

次の一方または両方が成り立つ場合です。

  • 実装し、既定で有効になっている主要なブラウザーが二つ未満であること。
  • 仕様の記述が安定しておらず、大きく変わる可能性があること。従って、仕様書の変更によって、将来の版のブラウザーで構文や動作が変更する可能性があること。

これらの定義のうちの一方または両方が成り立つ場合、その技術を様々な種類の製品プロジェクト (つまり、単なるデモまたは実験ではない場合) に使用する前に慎重に考えなければなりません。実験的の定義については、 browser-compat-data プロジェクトも参照してください。

逆に、以下のような場合は実験的とはいません。

  • 二つ以上の主要なブラウザーで実装されている。または、
  • 仕様の定義が安定していて、変化しそうにない。

アーカイブページ

アーカイブページは、MDN の古いコンテンツのアーカイブに保存されているページです。これらのページには古くなった情報が含まれているため、他の人にとっては直接役に立ちません。

最も一般的なのは、これらは廃止されてもはや信頼されるべきではない Mozilla プロジェクトに関係します。しかし、それらは有用な歴史的記録を形成するのでそれらを単純に削除するのではなく、その中に含まれるパターンやアイデアのいくつかは将来の作業に役立つかもしれません。 良い例は B2G (Firefox OS) プロジェクトです。

どのような時にページをアーカイブするか?

ページが上記の説明に合う場合は、ページをアーカイブする必要があります。ページをアーカイブするには、[ページ移動]機能 ([詳細]  -  [この記事を移動]) を使用して、ページを[アーカイブ]ページツリー (/ja/docs/Archive) に移動します。この機能を使用する権限がない可能性があります。ページのアーカイブを開始する前に、まず MDN コミュニティと話し合う必要があります - ディスカッションフォーラムで私たちに相談してください。

削除されたページ

削除されたページは、MDN から明示的に削除されたページです - 例えば SharedKeyframeList インターフェイスと SharedKeyframeList() コンストラクタを見てください。 これらのページには、もはや有用ではない情報が含まれています。また、利用可能にしておくと混乱したり、知っていたりすることが不適切な場合もあります。

これらはそうかもしれません:

  • ブラウザに実装される前に仕様から削除された API 機能の参照ページ
  • 後で悪い手法であることが示され、より良い技術によって置き換えられた技術をカバーする記事
  • 後で他のより質の高い記事に置き換えられた情報を含む記事
  • MDN に不適切なコンテンツを含む記事
  • 古く、時代遅れで、修正が難しい翻訳は英語版が優先され、新しい翻訳を開始することがより簡単なオプションになります

どのような時にページを削除するか

上記の説明に合う場合はページを削除する必要があります。ページを削除するには、[このページを削除] 機能 ([詳細設定]> [このページを削除]) を使用してページを削除します。あなたはおそらくこの機能を使う権限を持っていないでしょう、そしてページを削除することを考えるときあなたは最初にそれを MDN コミュニティと議論するべきです - ディスカッションフォーラムで私たちに相談してください。

新しい技術を記述するとき

MDN では、新しい Web 標準テクノロジを適切に文書化することを常に検討しています。私達は、開発者が必要なときにすぐに新機能について学ぶことができるようにドキュメントを十分に早く公開することと、定期的に更新したり迅速に削除したりする必要がないように技術が成熟し安定したものになるように十分に遅く公開することのバランスをとるようにしています。

一般的に、新しいテクノロジを文書化することを検討する最も早い定義は、次のとおりです。

「この機能が標準化過程にあり、どこかに実装されている場合」

次のような場合は、必ず新しいテクノロジを文書化することを検討してください。

  • 信頼できる標準化団体 (W3C、WHATWG、Khronos、IETFなど) の下で公開された仕様書で指定されており、妥当なレベルの安定性に達している (例えば、W3C のワーキングドラフトや候補者の勧告、あるいはそれに対して提起された問題の流れから判断すると、仕様はかなり安定しているように見えます)
  • 他のブラウザ開発者が興味を引く兆しを見せており、少なくとも1つのブラウザで一貫して実装されています (有効なチケットや「実装」プロセスなど)

次のような場合は、新しいテクノロジを文書化することにもっと慎重になる必要があります (ただし、意味がある場合はそれを考慮する必要があります)。

  • 仕様がない、あるいは、変更されやすいと思われる大まかな内容
  • 1つか0つのブラウザが現在それを実装しており、サポートしていないブラウザはそれを実装することに興味の兆しを見せていない (あなたはそれらのブラウザで働くエンジニアに尋ねることによってブラウザのバグトラッカーとメーリングリストなどを調べることによって評価できます)

次のような場合は、新しいテクノロジを文書化することを検討しないでください。

  • Webに公開された技術ではない、あるいは完全に独自の技術
  • すでに廃止されている、または同様の機能によって置き換えられているという兆候を示している

慣習

何かが仕様書から削除されたとき

ときに新しい仕様の開発中、または HTML などのリビングスタンダードの進化の過程で新しい要素、メソッド、プロパティなどが仕様に追加され、しばらくそのままにしてから再度削除されることがあります。時々これは非常に速く起こります、そしてこれらの新しい項目は削除される前に数ヶ月あるいは何年もの間仕様に残っています。これは仕様から項目の削除をどのように処理するか決定することを難しくします。ここにあなたが何をすべきかを決めるのを助けるいくつかのガイドラインがあります。

この説明の目的のために、「項目」という用語は、仕様の一部になり得るものすべてを意味するために使用されます。要素または要素の属性、インターフェイス、あるいは個々のメソッド、プロパティ、またはインターフェイスの他のメンバー などです。
  • If the item was never implemented in a release version of any browser—even behind a preference or flag—simply delete any references to the item from the documentation.
    • If the item has any documentation pages describing only that one item (such as RTCPeerConnection.close()), delete that page. If the removed item is an interface, this means removing any subpages describing the properties and methods on that interface as well.
    • Remove the item from any lists of properties, attributes, methods, and so forth. For methods of an interface, that means to remove it from the "Methods" section on the interface's overview page, for example.
    • Search the text of the overview page for that interface, element, etc. for any references to the removed item. Remove those references, being sure not to leave weird grammar issues or other problems with the text. This may mean not just deleting words but rewriting a sentence or paragraph to make more sense. It may also mean removing entire sections of content if the description of the item's use is lengthy.
    • Similarly, look for any discussion of the item in the guides and tutorials about the relevant API or technology. Remove those references, being sure not to leave weird grammar issues or other problems with the text. This may mean not just deleting words but rewriting a sentence or paragraph to make more sense. It may also mean removing entire sections of content if the description of the item's use is lengthy.
    • Search MDN for references to the removed item, in case there are discussions elsewhere. It's unlikely that there are, since if it was never implemented, it's unlikely to be widely discussed. Remove those mentions as well.
    • If the Browser Compatibility Data repository's JSON files contain data for the removed items, delete those objects from the JSON code and submit a PR with that change, explaining why in the commit message and the PR description. Be careful to check that you don't break the JSON syntax while doing this.
  • If the item was implemented in any release version of any one or more browsers—but only behind a preference or flag—do not delete the item from the documentation immediately. Instead, mark the item as deprecated as follows:
    • If the item has any documentation pages describing only that one item (such as RTCPeerConnection.close()), add the deprecated_header macro to the top of the page and add the tag to the page's list of tags.
    • On the overview page for the element, interface, or API, find the list of items which includes the item that's been removed from the specification and add the deprecated_inline macro after the item's name in that list.
    • Search the informative text of the overview page for that interface, element, etc. for any references to the removed item. Add warning boxes in appropriate places with text along the lines of "[whatever] has been removed from the specification and will be removed from browsers soon. See [link to page] for a new way to do this."
    • Similarly, look for any discussion of the item in the guides and tutorials about the relevant API or technology. Add similar warnings.
    • Search MDN for references to the removed item, in case there are discussions elsewhere. Add similar warning boxes there as well.
    • At some point in the future, a decision may be made to actually remove the item from the documentation; we don't normally do this but if the item was especially unutilized or uninteresting, we may decide to do so.
    • Update any relevant entries in the Browser Compatibility Data repo to reflect the obsolescence of the item(s) affected.
  • If the item was implemented in one or more release builds of browsers—without requiring a preference or flag to be changed—mark the item as deprecated, as follows:
    • If the item has any documentation pages describing only that one item (such as RTCPeerConnection.close()), add the deprecated_header macro to the top of the page and add the tag to the page's list of tags.
    • On the overview page for the element, interface, or API, find the list of items which includes the item that's been removed from the specification and add the deprecated_inline macro after the item's name in that list.
    • Search the informative text of the overview page for that interface, element, etc. for any references to the removed item. Add warning boxes in appropriate places with text along the lines of "[whatever] has been removed from the specification and is deprecated. It may be removed from browsers in the future, so you should not use it. See [link to page] for a new way to do this."
    • Similarly, look for any discussion of the item in the guides and tutorials about the relevant API or technology. Add similar warnings.
    • Search MDN for references to the removed item, in case there are discussions elsewhere. Add similar warning boxes there as well.
    • It's unlikely that these items will be removed from the documentation anytime soon, if ever. It's possible, however, that some or all of the material may be moved to the Archive section of the site.
    • Update any relevant entries in the Browser Compatibility Data repo to reflect the deprecation of the item(s) affected.

Please use common sense with wording of warning messages and other changes to text suggested by the guidelines above. Different items will require different wording and handling of the situation. When in doubt, feel free to ask for advice on the #mdn channel on IRC, or on the MDN Web Docs Discourse forum.

MDN 内でのコンテンツのコピー

ときどき、複数のページで同じテキストを再利用する必要が生じる場合(または、あるページを別のページのテンプレートとして利用したい場合)があります。その場合、3つの選択肢があります。

  • ページ全体をコピーしたい場合。
    1. コピーしたいページを閲覧中に、詳細(歯車)メニュー内にある、 この記事を複製を選んで下さい。新しいページのエディターのユーザーインターフェイスが、複製されたページの内容がすでに入った状態で開かれます。
    2. 新しいタイトルスラグを、複製したページに入力します。
    3. 必要に従ってページを編集し、通常と同じように保存します。
  • ページの一部分だけをコピーしたい場合は、ページの単純なコピーアンドペーストはやめて下さい。余計な HTML の断片を作成中のページに埋め込むことになり、誰かが片付けをすることになります。あなたかもしれないし、他の編集者かもしれませんが、誰もそんなことやりたくありません。 MDN のページの一部をコピーする場合、
    1. ソースページで、編集ボタンをクリックします。
    2. エディターの UI の中で再利用したい部分をコピーします。
    3. 変更を破棄をクリックして、エディターの UI を終了します。
    4. 貼り付けしたいページのエディターの UI を開きます。
    5. 内容をクリップボードから貼り付けします。
  • 文字通り、同じコンテンツを多くのページに利用したい場合もあるかもしれません。そんな時は、そのコンテンツを一つのページにまとめてしまうのがいいかもしれません。そして Page マクロを利用して、一つのページから他のページへ素材を転写しましょう。こうすると、参照元のページが更新されると、参照先のページの内容も同様に更新されます(これは強制的に更新したり、参照先のページが定期的に再構築されたりした際に起こります)。

他の場所からの内容のコピー

多くの場合、MDN 以外にも Web 上のどこかにトピックに関する有用なコンテンツがあります。しかし、そのようなコンテンツをコピーすることは、法的にも技術的にも困難を伴うことがあります。

技術的なレベルでは、検索エンジンは通常他の場所で利用可能なコンテンツを再生するために彼らのランキングでサイトにペナルティを課します。したがって、MDN のコンテンツの検索エンジンのランキングを向上させるために、MDN にオリジナルのコンテンツを含めることが好ましいです。MDN から既存のコンテンツにリンクできます。

法的なレベルでは、あなたはコンテンツを寄付する権限を与えられなければならず、そしてそれは MDN のライセンスと互換性のある方法でライセンスされそして帰属しなければなりません。

  • 既存のコンテンツを作成し (あなた自身の目的のためであり、仕事用としてではなく)、それを MDN のライセンスの下で MDN に寄付する意思がある場合、これが最も簡単なケースであり、自由にコンテンツを寄付できます
  • コンテンツの著作権が他の人に帰属する場合、それは MDN のライセンスと互換性があるようにライセンスされている必要があります。弁護士ではない人にとって、互換性のあるライセンスを判断するのは容易ではありません。安全のため、必要に応じて MDN スタッフチームのメンバーに連絡してください

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

このページの貢献者: silverskyvicto, mfuji09, wbamberg, Uemmra3, 5ara5treamer
最終更新者: silverskyvicto,