ジャンプ先:

この翻訳は不完全です。英語から この記事を翻訳 してください。

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

定義

非推奨と廃止

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

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

実験的 (Experimental)

Experimental can mean different things depending on the context you hear or read it in. When a technology is described as experimental on MDN, it means that the technology is nascent and immature, and currently in the process of being added to the Web platform (or considered for addition).

One or both of these will be true:

  • It is implemented and enabled by default in less than two modern major browsers.
  • Its defining spec is not stable and likely to change significantly. Its syntax and behavior is therefore subject to change in future versions of browsers as the specification changes.

If one or both of these definitions is true, then you should think carefully before you start using that technology in any kind of production project (i.e. not just a demo or experiment). See also the definition of experimental in our browser-compat-data project.

Conversely, an item is no longer experimental when:

  • It is implemented in two or more major browsers; or
  • Its defining spec is stable and unlikely to change.

アーカイブページ

Archived pages are pages that are stored in the MDN Archive of obsolete content. These pages contain information out-of-date enough that it is not directly useful to anyone anymore.

Most commonly, these concern Mozilla projects that have been discontinued and shouldn't be relied on anymore. But we don't simply delete them because they form a useful historical record, and some of the patterns or ideas contained within might be useful for future work. A good example is the B2G (Firefox OS) project.

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

A page should be archived if it fits the above description. To archive a page, you should use the "Move page feature" (Advanced > Move this article) to move the page into the Archive page tree (/ja/docs/Archive). You might not have the permissions to use this feature, and before you start archiving pages you should discuss it with the MDN community first — talk to us on our Discourse forum.

削除されたページ

Deleted pages are pages that have been explicitly deleted from MDN — see for example the SharedKeyframeList interface and SharedKeyframeList() constructor. These pages contain information that is not useful in any way anymore, and/or might be incorrect to the point where keeping it available might be confusing or bad for people to know.

These might be:

  • Reference pages for API features that were removed from the specification before they were implemented in any browsers.
  • Articles covering techniques that were later shown to be bad practice and superceded by better techniques.
  • Articles containing information that were later replaced by other, better quality articles.
  • Articles containing content that is inappropriate for MDN.
  • Translations that are old, out-of-date, and difficult to fix, meaning that the English version is preferrable and starting a new translation would be an easier option.

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

A page should be deleted if it fits the above description. To delete a page, you should use the "Delete this page feature" (Advanced > Delete this page) to delete the page. You will probably not have the permissions to use this feature, and when thinking about deleting pages you should discuss it with the MDN community first — talk to us on our Discourse forum.

 

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

On MDN, we are constantly looking to document new web standards technologies as appropriate. We try to strike a balance between publishing the documentation early enough so developers can learn about new features as soon as they need to, and publishing it late enough so that the technology is mature and stable so the docs won't need constant updates or rapid removal.

In general, our definition of the earliest we'll consider documenting a new technology is:

"When the feature is on a standards track and is implemented somewhere."

You should definitely consider documenting a new technology if:

  • It is specified in a specification document published under a reliable standards organization (such as W3C, WHATWG, Khronos, IETF, etc.), which has reached a reasonable level of stability (e.g. a W3C working draft or candidate recommendation, or the spec is looking to be fairly stable judging by the flow of issues filed against it).
  • It is implemented consistently in at least one browser, with other browser developers showing signs of interest (such as an active ticket or "intent to implement" process in effect).

You should be more wary of documenting a new technology (but should still consider it if it makes sense) if it:

  • Doesn't have a spec, or the spec is a rough note that looks liable to change.
  • One or zero browsers currently implement it, and non-supporting browsers are not showing signs of interest in implementing it (you can gauge this by asking engineers who work on those browsers, looking at browser bug trackers and mailing lists, etc.).

You should not consider documenting a new technology if it:

  • Is not a web-exposed technology and/or is completely proprietary.
  • Is already showing signs of being deprecated, or superseded by a similar feature.

 

慣習

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

Sometimes during the development of a new specification, or over the course of the evolution of living standards such as HTML, new elements, methods, properties, and so forth are added to the specification, stay there for a while, then get removed again. Sometimes this happens very quickly, and sometimes these new items remain in the specification for months or even years before being removed. This can make it tricky to decide how to handle the removal of the item from the spec. Here are some guidelines to help you decide what to do.

For the purposes of this discussion, the word "item" is used to mean anything which can be part of a specification: an element or an attribute of an element, an interface or any individual method, property, or other member of an interface, and so forth.

  • 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 マクロを利用して、一つのページから他のページへ素材を転写しましょう。こうすると、参照元のページが更新されると、参照先のページの内容も同様に更新されます(これは強制的に更新したり、参照先のページが定期的に再構築されたりした際に起こります)。

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

Often, there is useful content about a topic somewhere on the web besides on MDN. However, copying such content can be fraught with difficulties, both legal and technical.

On the technical level, search engines typically penalize a site in their rankings for reproducing content available elsewhere. Therefore, it is preferable to have original content on MDN, to enhance the search engine ranking of MDN's content. You can link to the existing content from MDN.

On the legal level, you must be authorized to contribute the content, and it must be licensed and attributed in a way that is compatible with MDN's license.

  • If you created the existing content (for your own purposes and not as work-for-hire), and you are willing to contribute it to MDN under MDN's license, this is the easiest case, and you are free to contribute the content.
  • If the copyright for the content belongs to someone else, it must be licensed and attributed compatibly with MDN's license. It is often not easy for someone who is not a lawyer to determine what licenses are compatible. To be on the safe side, contact a member of the MDN staff team, who may consult Mozilla's Legal team for guidance if necessary.

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

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