外部コンテンツを MDN Web Docs に移行する方法

他の場所から MDN Web Docs に移行することに意味のある既存のコンテンツが見つかることがあります。この記事では、どのような種類のコンテンツを移行することが意味のあることなのか、コンテンツを移行すべきかどうか、移行を行うためにどのようなワークフローを使用すべきかについて説明します。

どのようなコンテンツが移行することに意味があるのか

MDN Web Docs に移行することに意味があると思われるコンテンツの種類はいくつかあります。

  • チュートリアル/ガイド: の使用に関する実用的な情報。これらは MDN Web Docs 上でレベルや範囲に応じて様々な場所で役立ちます (例: Fetch の使用、ハイパーリンクの作成)。
  • 解説/概念の記事: これらは一般的に、 API がなぜそのような構造になっているのか、どのような問題を解決するために設計されているのかなど、高レベルの概念を説明するものです。これらは「概念」記事 (例えば WebVR の概念) として意味があります。
  • コード例: MDN Web Docs は、参照記事の中に入れるコードスニペットであれ、リンク先の完全な例であれ、良いコード例を本当に大切にしています。私たちは、スタンドアロンの例として、または対話型の例のリポジトリの一部として、優れたコード例を GitHub リポジトリに歓迎します。

MDN Web Docs に移行しても意味がないコンテンツは下記のとおりです。

  • 長い事例研究
  • 製品のドキュメント
  • 宣伝コンテンツ

なぜコンテンツを移行するのか

良い開発者向けコンテンツがすでに存在するのであれば、いくつかの理由から MDN Web Docs に移行することには意味があります。

  • SEO: MDN Web Docs はとても有名なサイトで、そこにあなたのコンテンツを置くことは、より見つけやすくするための良い方法です。
  • 車輪の再発明ではないこと: MDN Web Docs のドキュメントは完全であることを誇りとしています。つまり、重要なリファレンスやチュートリアルはすべて他の場所にリンクするのではなく、サイト上に書く必要があるということです。既存のチュートリアルをここに置くことは、それを書く必要がないことを意味します。 ;-)
  • 改訂とメンテナンス: あなたのコンテンツを MDN Web Docs に掲載すると、ライターチームとコミュニティの全面的な支援を受けて、作品のレビュー、編集、メンテナンスを行うことができます。

コンテンツを移行すべきか

コンテンツの質が高く、上記のコンテンツタイプの基準を満たしているのであれば、移行しても良さそうです。しかし、まずは以下の点を考慮してから移行するようにしましょう。

  • コンテンツの重複: 移動させたいリソースは、すでに MDN Web Docs 上にあるコンテンツと重複していますか？もしそうであれば、別のリソースを移動させるのではなく、既存のリソースを改善することのほうが意味があるかもしれません。外部リソースが既存のリソースよりもはるかに優れている場合は、そのリソースを移動し、古いリソースが新しいリソースにリダイレクトされていることを確認してください。
  • どこに置くか: リソースの移動先がわからない場合は、まず私たちに相談してください (会話に参加するを参照してください)。
  • 所有権。コンテンツの権利を所有していない場合は、所有者の許可を得ずに移動することはできません。まず所有者に連絡して、それについて話し合う必要があります。コンテンツがある種の寛容なライセンススキーム (クリエイティブ・コモンズやGPLなど) の下で公開されている場合は、ライセンス条件が満たされていることを確認してください。気軽に私たちに相談してください。
  • コミュニティの満足度を維持する: コンテンツを所有していても、その周りにコミュニティがある場合は、コミュニティに相談する必要があります - 彼らの意見を聞き、何が起こっているのかを理解してもらい、コンテンツの移動に伴う混乱や迷惑を最小限に抑えましょう。
  • リダイレクト: コンテンツリソースを移動する際には、リンクが切れないように、古いコンテンツを新しい場所にリダイレクトするのが一般的です。これが意味を成さない場合もあります。例えば、移動したコンテンツがオリジナルのテンプレートのコピーであり、両方のコンテンツが存在する文脈の中でしか意味を成さない場合などです。新しいバージョンへのリンクをどこかで提供することで、2つの関係が明確になることがよくあります。
  • 意味のあるものにする。コンテンツが移動された場合、古い場所と新しい場所にあるリソースはまだ意味がありますか？これを確実にするために、説明やナビゲーションメニューを更新する必要があるかもしれません。

移行のワークフロー

以下は、コンテンツを MDN Web Docs に移行するためのワークフローの例です。 この GitHub の問題で記録されているように、 W3C Payment Request のコードを MDN に移行しました。

  1. 移行するリソースを特定する。
  2. コンテンツの所有者を特定し、コンテンツの移動が問題にならないことを確認するために、その所有者や関連するコミュニティと話をします。
  3. 移行を支援してくれる MDN Web Docs の担当者を特定します。疑問がある場合は、MDN のコンテンツ担当者である Chris Mills に相談してみましょう。
  4. MDN/our GitHub org を見て、コンテンツを置く場所を特定し、既存のコンテンツと重複していないことを確認します (上記参照)。
  5. MDN のスタイルに合うように、必要に応じて変更を加えながらコンテンツを移動させます。
  6. MDN チーム/コミュニティにレビューを依頼します。
  7. 必要に応じて、古いリソースから新しい場所にリダイレクトします。