From 20f40b42cd50b62ee767cdeea5022d8066512ec6 Mon Sep 17 00:00:00 2001 From: Masahiro FUJIMOTO Date: Fri, 30 Jul 2021 13:36:23 +0900 Subject: MDN/Guidelines/Writing_style_guide 以下を削除 (#1600) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - MDN/Guidelines/Writing_style_guide 以下を削除 - 関連るする文書も最小限の修正を実施 --- .../guidelines/does_this_belong_on_mdn/index.html | 124 ++++----------------- 1 file changed, 19 insertions(+), 105 deletions(-) (limited to 'files/ja/mdn/guidelines/does_this_belong_on_mdn') diff --git a/files/ja/mdn/guidelines/does_this_belong_on_mdn/index.html b/files/ja/mdn/guidelines/does_this_belong_on_mdn/index.html index 64d4de378a..1b8f12161e 100644 --- a/files/ja/mdn/guidelines/does_this_belong_on_mdn/index.html +++ b/files/ja/mdn/guidelines/does_this_belong_on_mdn/index.html @@ -1,5 +1,5 @@ --- -title: これは MDN Web Docs に掲載するものですか？ +title: MDN Web Docs に掲載するものであるかどうか slug: MDN/Guidelines/Does_this_belong_on_MDN tags: - Guide @@ -9,11 +9,9 @@ translation_of: MDN/Guidelines/Does_this_belong_on_MDN ---
{{MDNSidebar}}
-
{{IncludeSubnav("/ja/docs/MDN")}}
-

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

-

問い

+

問い

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

@@ -24,55 +22,55 @@ translation_of: MDN/Guidelines/Does_this_belong_on_MDN
  • 文書の性質 (これはどんな種類の文書か)
    • -

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

    +

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

    -

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

    +

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

    -

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

    +

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

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

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

    -

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

    +

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

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

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

    -

    MDN Web Docs に掲載しない主題

    +

    MDN Web Docs に掲載しない主題

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

    -

    Mozilla 製品

    +

    Mozilla 製品

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

    -

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

    +

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

    -

    それ以外

    +

    それ以外

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

    @@ -103,7 +101,7 @@ translation_of: MDN/Guidelines/Does_this_belong_on_MDN
  • エンドユーザー向け文書。Mozilla 製品では、こうした文書は Mozilla サポートサイトに載っています。
    • -

    MDN に掲載する文書の種類

    +

    MDN に掲載する文書の種類

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

    @@ -114,89 +112,5 @@ translation_of: MDN/Guidelines/Does_this_belong_on_MDN
  • 設計書
  • プロジェクト提案書
  • 仕様書や標準
    • -
  • プロモーション素材、広告、個人情報
    • +
  • プロモーション素材、広告、個人情報
    • - -

    MDN で文書化する利点

    - -

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

    - -

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

    - -

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

    - - - -

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

    - -

    保守

    - -

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

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

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

    - -

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

    - -

    計画書や手順書

    - -

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

    - -

    Github 上のプロジェクト

    - -

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

    - - - -

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

    - -

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

    - -

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

    - -

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

    - - - -

    欠点もあります。

    - - - -

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

    - -

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

    - -

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

    -- cgit v1.2.3-54-g00ecf