ウェブ開発の学習の執筆ガイドライン

MDN ウェブ開発学習（別名「学習」）の対象者は、フロントエンド開発のエキスパートではない人々です。これには、ウェブ開発を学ぶ学生、初心者、研修生、趣味でウェブ開発を行う人々、また、生徒に何を教えるべきかについての最善の手法を求めている教師などが含まれます。

学習では、学習成果が含まれている構造化された学習経路が指定されており、読者がフロントエンド開発者として成功するために必要な基本的なスキルと実践を習得できるよう設計されています。学習者は、学習に必要な正しい情報を提供してくれるこの教材を信頼することができます。また、教育者は、この教材が正しい学習成果を提供してくれることを信頼し、この教材を基にコースやカリキュラムを設計することができます。

そのため、「学習」のスコープを厳しく制限することを目指しています。

• 入門モジュールでは、セットアップ、ソフトスキル、背景知識。
• コアモジュールでは、ウェブ開発を始めるにあたって要求される基本技術。
• 発展モジュールでは、「次の段階」のトピックで、相対的な初心者の方がコアモジュールを習得した後に学ぶ、有益な次の段階のもの。

学習では、 MDN ですべてのトピックに関する入門コンテンツを用意することを意図したものではありません。つまり、 MathML やウェブゲームなどのニッチなトピック、、正規表現、パフォーマンステスト、WebRTC、WebGPU などの高度なトピックや専門的なトピックは、学習に属するものではないということです。

学習でカバーされていないトピックがあり、それを扱うべきだと考える場合は、ただ追加しようとするのではなく、まず私たちディスカッションしてください（コンテンツの提案として）。

MDN のウェブ開発の学習コンテンツを新規作成したり更新したりするには、多くの点で、 MDN の他の部分と同じ手法に従う必要があります。一般的な執筆スタイルガイド、コードスタイル、テクニックについても同じものに従う必要があります。

ただし、若干の違いもあります。

• チュートリアルスタイル: MDNで提供されている他のコンテンツのほとんどは、リファレンス素材とガイドの組み合わせです。一方、学習は、ハンズオンのチュートリアルを提供することを意図しています。各ページに厳密なテンプレートがあるわけではありませんが、手順を追った節と「試してみよう」の節を組み合わせて、読者を導くような書き方をすべきです。これらは、読者に飛び込んで試してみるように指示し、コードを書き始めるようにすべきです。例えば、検索エンジン情報の下部の「試してみる」の節をご覧ください。これらは次の Markdown を使用して作成されています。

  markdown

  > [!CALLOUT]
  >
  > **試してみる**
  >
  > 検索エンジンを用いて...
  

• 課題: 学習コンテンツには、定期的に課題を記載し、読者がそれまで学習したトピックを理解しているかどうかを確認します。 これらは現在、いくつかの異なるスタイルで作成されています。例えば、 課題: コンテンツのページの構造化やスキルテスト: HTML 画像を参照してください。しかし、今後はこれらの一貫性と使い勝手を改善していく予定です。

• 密度と完全性：MDNコンテンツは一般的に、その包括性で知られています。学習コンテンツは、MDNの他のコンテンツほど完全に網羅されているわけではありません。学習者が圧倒されることなく、役立つスキルを習得し、定期的に学習を進められるよう、密度は低く、より穏やかな手法が採用されています。必要に応じて、後でより深く掘り下げることもできます。学習コンテンツでは、読者に誤解を招くようなことや、悪い習慣を教えることがないようであれば、より快適な学習体験を提供するために詳細を省略できます。

• 安定した学習成果：各チュートリアルの一番上に表示される学習成果は、各チュートリアルで学べる内容の概要を指定したもので、全体として、ウェブ開発のフロントエンドに関する体系的なカリキュラムを提供します。学習成果と教える内容の両方が安定しており、同期していることが重要です。そうでなければ、そのコンテンツは正式な学習（例えば、資格情報の教育コース）の基礎として信頼できません。そのため、学習成果の変更はゆっくりと行われるべきであり、理由なく変更されるべきではありません。 関連付けられた学習成果に応じたコンテンツではないものを追加しようとした場合（またはその逆の場合）、プルリクエストは閉じられます。先に提案を行ってください。

外部リンクに関するガイドラインの概要で説明されているように、MDNでは一般的に、商業製品やサービスを推奨しているように見える外部リンク（または埋め込み）や、有料コンテンツへのリンクは許可されていません。これは、MDNのコンテンツがスパムリンクで溢れかえり、信頼を失い、有用性が低下するリスクを軽減するためです。

MDN の学習コンテンツでは、これについてのいくつかの例外があります。特定の信頼できるパートナーサイトの（有料コンテンツを持っている可能性がある）外部コンテンツへのリンクを許可しています。これらは、 MDN がその品質、倫理、ウェブ標準や最善の手法への取り組みを徹底的に調査し、 MDN の基準を満たしていないコンテンツの更新を支援することで、信頼関係を築いてきたサイトです。私たちは、それらのサイトが予告なしにリンクを変更することはないと信頼しており、それらのコンテンツにリンクしても安全であると信頼しています。

これらのパートナーリンクの目的は次の通りです。

• 当社のページで教えられている内容に対応するコンテンツにアクセスできるように指定して提供すること。
• MDN のコンテンツチームが制作するリソースにないマルチメディア学習コンテンツ（動画、スライドショー、その他のインタラクティブコンテンツ）にアクセスできるようにすること。私たちは MDN のテキストコンテンツにすべてを注いでいますが、他の学習方法を求める人もよくいるからです。
• MDN をさらに良くするために投資できる有料コンテンツへのアフィリエイトリンクを通じて収益を得ることができます。

ただし、私たちは次のことを行います。

• MDN のコンテンツの完全性を損なう方法や、スパム的な方法でリンクを追加することはありません。本当に有益な場合のみ追加します。
• 常に、有料のコンテンツの他に、無料のオプションが利用できることを確認します。多くの場合、以前有料だったコンテンツを無料で利用できるように、パートナーを管理しています。
• パートナーコンテンツには「MDN 学習パートナー」というラベルを明確に付け、他のリンクと明確に区別できるようにします。

「学習」コンテンツページでは、ページ下部に現れる「関連情報」のリンクは次の順序で表示するようにします。

1. 内部リンク。
2. 無慮コンテンツへのリンク
3. 無料と有料が混在したコンテンツへのリンク。

• Scrimba