---
title: MDN の慣習と定義
slug: MDN/Guidelines/Conventions_definitions
tags:
- MDN
- MDN Meta
- ガイド
- ガイドライン
- ドキュメント
translation_of: MDN/Guidelines/Conventions_definitions
---
{{MDNSidebar}}{{IncludeSubnav("/ja/docs/MDN")}}
この記事では MDN で使用されている慣習や定義、特に文書化する際に人によっては忘れがちなものを紹介します。
定義
非推奨と廃止
非推奨や廃止は技術や仕様書によく使われている言葉ですが、どのような意味でしょうか？
- 非推奨
- MDN において非推奨 の用語は、もう推奨されないものの、まだ実装されており動作する可能性がある API や技術を示すために使用されます。最近では、 browser-compat-data プロジェクトの中で使用される定義を、「その機能はもう推奨されません。将来は削除されるか、互換性のためだけに温存される可能性があります。この機能を使用することは避けてください。」と更新しました。
- 廃止
- MDN において廃止 の用語は、もう推奨されないだけでなく、ブラウザーでももう実装されていない API や技術を示すために使用されます。しかし、これは混乱しやすもののです。 — 非推奨に似ており、区別することがさほど役立たない (こちらも本番サイトでは使用するべきではない) ものです。従って、私たちはこれを使用するのをやめ、使用されている記述を削除するか、非推奨に置き換えるかしてください。
実験的
実験的は、聞いた場所や読んだ場所の文脈によって意味が異なる可能性があります。 MDN においてある技術が実験的と記述されている場合、その技術は生まれたばかりで未熟であり、現在ウェブプラットフォームへの追加手続の途中の (または追加が検討されている) 段階であることを意味します。
次の一方または両方が成り立つ場合です。
- 実装し、既定で有効になっている主要なブラウザーが二つ未満であること。
- 仕様の記述が安定しておらず、大きく変わる可能性があること。従って、仕様書の変更によって、将来の版のブラウザーで構文や動作が変更する可能性があること。
これらの定義のうちの一方または両方が成り立つ場合、その技術を様々な種類の製品プロジェクト (つまり、単なるデモまたは実験ではない場合) に使用する前に慎重に考えなければなりません。実験的の定義については、 browser-compat-data プロジェクトも参照してください。
逆に、以下のような場合は実験的とは言いません。
- 二つ以上の主要なブラウザーで実装されている。または、
- 仕様の定義が安定していて、変化しそうにない。
ここではまたはが重要です。 — 通常、ある技術に複数の主要なブラウザーが対応した場合、仕様は安定するでしょうが、これは常に言えるわけではありません。また、技術によっては安定した仕様書がありよく使用されてはいるものの、ブラウザーでのネイティブな対応がない場合もあります (IMSC などがその例)。
アーカイブページ
アーカイブページは、 MDN の古いコンテンツのアーカイブに保存されているページです。これらのページには古くなった情報が含まれているため、他の人にとっては直接役に立ちません。
最も一般的なのは、これらは廃止されてもはや信頼されるべきではない Mozilla プロジェクトに関係します。しかし、それらは有用な歴史的記録を形成するのでそれらを単純に削除するのではなく、その中に含まれるパターンやアイデアのいくつかは将来の作業に役立つかもしれません。 良い例は B2G (Firefox OS) プロジェクトです。
どのような時にページをアーカイブするか？
ページをアーカイブするべきである場合は、ページが上記の説明に合う場合です。ページをアーカイブするには、[ページ移動]機能 ([詳細] - [この記事を移動]) を使用して、ページを[アーカイブ]ページツリー (/ja/docs/Archive) に移動します。この機能を使用する権限がない可能性があります。ページのアーカイブを開始する前に、まず MDN コミュニティと話し合う必要があります - ディスカッションフォーラムで私たちに相談してください。
削除されたページ
削除されたページは、 MDN から明示的に削除されたページです - 例えば SharedKeyframeList インターフェイスと SharedKeyframeList() コンストラクターを見てください。 これらのページには、もはや有用ではない情報が含まれています。また、利用可能にしておくと混乱したり、知っていたりすることが不適切な場合もあります。
次のようなものが該当する可能性があります。
- ブラウザーに実装される前に仕様から削除された API 機能のリファレンスページ
- 後で悪い手法であることが示され、より良い技術によって置き換えられた手法をカバーする記事
- 後で他のより質の高い記事に置き換えられた情報を含む記事
- MDN に不適切なコンテンツを含む記事
- 古く、時代遅れで、修正が難しい翻訳記事で、すなわち英語版が推奨されて翻訳し直した方が簡単である場合
どのような時にページを削除するか
上記の説明に合う場合はページを削除する必要があります。ページを削除するには、[このページを削除] 機能 ([詳細設定] > [このページを削除]) を使用してページを削除します。あなたはおそらくこの機能を使う権限を持っていないでしょう、そしてページを削除することを考えるときあなたは最初にそれを MDN コミュニティと議論するべきです - ディスカッションフォーラムで私たちに相談してください。
新しい技術を記述するとき
MDN では、新しいウェブ標準技術を適切に文書化することを常に検討しています。私達は、開発者が必要なときにすぐに新機能について学ぶことができるように文書を十分に早く公開することと、定期的に更新したり迅速に削除したりする必要がないように技術が成熟し安定したものになるように十分に遅く公開することのバランスをとるようにしています。
一般的に、新しい技術を文書化することを検討する最も早い定義は、次のとおりです。
「この機能が標準化過程にあり、どこかで実装されている場合」
新しい技術を文書化することを絶対的に考えるべきであるのは以下のような場合です。
- 信頼できる標準化団体 (W3C、WHATWG、Khronos、IETFなど) の下で公開された仕様書で指定されており、妥当なレベルの安定性に達している (例えば、 W3C のワーキングドラフトや候補者の勧告、あるいはそれに対して提起された問題の流れから判断すると、仕様はかなり安定しているように見えます)
- 他のブラウザー開発者が興味を引く兆しを見せており、少なくとも1つのブラウザーで一貫して実装されている場合 (有効なチケットや「実装」プロセスなど)
次のような場合は、新しいテクノロジを文書化することにもっと慎重になるべきです (ただし、意味がある場合はそれを考慮する必要があります)。
- 仕様書がない、あるいは、変更するべきであるような大まかなメモでしかない場合
- 現在それを実装しているブラウザーがゼロまたは1種類であり、対応していないブラウザーが実装する様子を見せていない場合 (それらのブラウザーの開発をしているエンジニアに尋ねたり、ブラウザーのバグトラッカーやメーリングリストなどを調べたりすることで評価することができます)。
次のような場合は、その新しい技術を文書化しようと考えないでください。
- ウェブに公開された技術ではない場合や、完全に私有の技術である場合
- すでに非推奨になっている、または同様の機能によって置き換えられる見込みがある
慣習
何かが仕様書から削除されたとき
新しい仕様の開発中や、 HTML のようなリビングスタンダードの進化の過程で、新しい要素、メソッド、プロパティなどが仕様書に追加され、しばらく存在してから削除されることが時々あります。これはとても速い周期で行われることもあれば、新しい項目が仕様書に数か月から数年の間、削除されずに残っていることもあります。これによって、仕様書から項目が削除されたと判断することが難しくなっています。どうするべきかを決める参考となるガイドラインをいくつか紹介します。
ここでは「項目」という単語を、仕様書の一部になりうるものすべてを示す意味で使用しています。要素や要素の属性、インターフェイスや個々のメソッド、プロパティ、またはインターフェイスの他のメンバーなどがこれに該当します。
- その項目がどのブラウザーのリリース版でも決して実装されていない場合 — 設定やフラグで隠されている場合を含めて — 単純にその項目のリファレンスを文書から削除してください。
- If the item has any documentation pages describing only that one item (such as {{domxref("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.
- アイテムが1つ以上のブラウザーのリリースバージョンに実装している場合 — ただし、設定またはフラグの背後にのみ — ドキュメントからすぐに削除しないでください。代わりに、次のように非推奨としてアイテムをマークします:
- If the item has any documentation pages describing only that one item (such as {{domxref("RTCPeerConnection.close()")}}), add the {{TemplateLink("deprecated_header")}} macro to the top of the page and add the {{tag("Deprecated")}} 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 {{TemplateLink("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.
- アイテムがブラウザーの1つ以上のリリースビルドで実装された場合 — 設定やフラグを変更する必要な し— 次のように、アイテムを非推奨としてマークします:
- If the item has any documentation pages describing only that one item (such as {{domxref("RTCPeerConnection.close()")}}), add the {{TemplateLink("deprecated_header")}} macro to the top of the page and add the {{tag("Deprecated")}} 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 {{TemplateLink("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 Web Docs chat room on Matrix, or on the MDN Web Docs discussion forum.
MDN 内でのコンテンツのコピー
ときどき、複数のページで同じテキストを再利用する必要が生じる場合 (または、あるページを別のページのテンプレートとして利用したい場合) があります。その場合、3つの選択肢があります。
他の場所からの内容のコピー
多くの場合、MDN 以外にも Web 上のどこかにトピックに関する有用なコンテンツがあります。しかし、そのようなコンテンツをコピーすることは、法的にも技術的にも困難を伴うことがあります。
技術的なレベルでは、検索エンジンは通常他の場所で利用可能なコンテンツを再生するために彼らのランキングでサイトにペナルティを課します。したがって、MDN のコンテンツの検索エンジンのランキングを向上させるために、MDN にオリジナルのコンテンツを含めることが好ましいです。MDN から既存のコンテンツにリンクできます。
法的なレベルでは、あなたはコンテンツを寄付する権限を与えられなければならず、そしてそれは MDN のライセンスと互換性のある方法でライセンスされそして帰属しなければなりません。
- 既存のコンテンツを作成し (あなた自身の目的のためであり、仕事用としてではなく)、それを MDN のライセンスの下で MDN に寄付する意思がある場合、これが最も簡単なケースであり、自由にコンテンツを寄付できます
- コンテンツの著作権が他の人に帰属する場合、それは MDN のライセンスと互換性があるようにライセンスされている必要があります。弁護士ではない人にとって、互換性のあるライセンスを判断するのは容易ではありません。安全のため、必要に応じて MDN スタッフチームのメンバーに連絡してください
仕様書が競合したときの調整方法
なお、時々 (まれに) 仕様書の異なるバージョン (特に W3C と WHATWG) が競合することがあり、例えば一方のバージョンがある機能を非推奨とする一方で、もう一方が非推奨にしない場合などがあります。このような場合、何が真実なのか — 例えば、ブラウザーは実際にどうしているか — を考慮し、「重要」なメモを書いて最新の状態を要約してください。例えば、2019年1月時点の inputmode グローバル属性には競合があり、次のように要約されています。