MDN 学習エリアにはウェブ開発の初心者向けの記事がまとまっています。ほとんどの内容が初心者向けであるため、知識を共有したりウェブへの入門者を手助けするのに良い場所となっています。ウェブ開発初心者でも内容を理解できることが大事なので、それについて特に注意を払っています。


この記事は学習エリアのページの書き方を説明しています。

訳注: この記事は英語の学習エリア記事を新規作成する方法について述べています。日本語の記事は英語記事を翻訳して作成してください。英語ページに該当する記事がない場合は、まず英語記事を作成してください。

学習エリアの記事の書き方

記事を書き始めるために、大きい緑のボタンをクリックし、以降の 6 つのステップを踏みましょう。もしアイデアを探しているなら、私たちのチームの Trello のボードを参考にしてみてください。

この記事の場所は正しくないかもしれませんが、少なくとも MDN 上にあります。もし正しい場所へ移動するために誰かと連絡を取りたい場合、こちらからお願いします。

ステップ 1: 概要を 2行で書く

1行目には書こうとしている主題の要約を書きましょう。2行目には記事に書こうとしている項目の詳細を少しだけ加えましょう。
例えば:

HTML ファイルが構造的なコンテンツを持つ一方、もうひとつの主要なウェブ技術である CSS は、開発者の望むように見た目を作ります。この記事では、CSS がどう動いているかと、基本的な書き方のサンプルを紹介します。

上記の例では、CSS がページをスタイルするためのウェブ技術の核であることを簡潔に説明しています。これにより、読者は記事が対象とする範囲を予想するのに十分な情報を得ることができます。

学習エリアの主な対象者は初心者です。そのため個々の記事は、読者があまりにも多い情報に圧倒されないように、1 つの単刀直入なテーマを対象にすべきです。もし要約が 1行に収まらない場合、1 つの記事に過剰な内容を書こうとしているかもしれません!

ステップ 2: 前提知識と到達目標を追加する

次に、読者が記事を読む前の準備ができるように、前提知識と到達目標を追加しましょう。以下は "JavaScript とは" の例です。記事を書く際の参考として利用しましょう。

前提知識: 基本的なコンピューターリテラシー、HTML および CSS の基本的な理解。
到達目標: JavaScript とは何か、何ができるか、どのようにウェブサイトに適用できるかについて親しむ。
前提知識
読者が記事を読む際に事前に知っておくべきことを書きます。可能なら、個々の前提知識に、その概念を網羅する他の学習エリア記事のリンクをつけます (本当に初歩の記事で、前提知識を網羅する要求しない場合を除く)。
到達目標
読者が記事を読んだ後に何を学べるかを簡潔に書きます。記事の冒頭に書く要約とは少し違って、この到達目標の節では、読者が記事を読むことで達成を期待されるものを具体的に示します。

注記: このテーブルをつくるためには、上記のサンプルをコピー&ペーストするか、MDN エディターのを使います。表を使う場合、CSS の class 属性に既定値の standard-table クラスに加えて learn-box クラスを追加する必要があります。表をクリックした後、表のプロパティで "高度な設定" のスタイルシートクラス に "standard-table learn-box" を設定します。

ステップ 3: 詳細説明を書く

次に、記事で最も強調したい概念についての徹底的な概要となるような、もっと長くて詳細な説明を書きましょう。なぜ読者が時間を費やしてこの記事を読み、その内容を学ぶべきかについての説明を忘れないように!

ステップ 4: 深掘りする

これまでの部分をやり終えたら、トピックを深掘りしましょう。記事を好きなように構造化して問題ありません(スタイルガイドをお気軽に参照ください)。このパートはあなたの記事を輝かせるチャンスです!書こうとしている内容を詳しく説明しましょう。参考情報へのリンクを加え、その技術がどのように動くのかを詳しく説明し、文法や使い方の詳細などを書きましょう。すべてあなた次第です!

ガイドとして、以下は初心者向けの書き方のコツです。

  • ひとつのトピックに集中しましょう。もし他のトピックについて書く必要性を感じたなら、前提知識の記載に漏れがあるか、別の記事として分割する必要がありそうです。
  • シンプルな言葉を使いましょう。できるだけ専門的な用語は避けましょう。最低限、それらの用語の意味を定義し、適当なものがあれば用語集へのリンクを貼るようにしましょう。
  • 理論的な概念を簡単に理解できるように、単刀直入なサンプルを含めましょう。多くの人は実例を通じて最もよく学習できます。学術論文を書くより、初心者にとって読みやすい文章を優先しましょう。
  • 視覚的な資料はより多くの情報を表し、理解の助けになることが多いです。なので画像、図表、動画、表を気軽に利用しましょう。図表やグラフにテキストを含めたいなら、我々の翻訳チームがローカライズに対応できるよう、SVG を使用することをお勧めします。

関数 — 再利用可能なコードブロックの記事には良い説明が含まれています。参考にしてみてください。

ステップ 5: 「アクティブラーニング」の教材を提供する

記事を解説し読者の理解を助けるために、実習、チュートリアル、達成すべきタスクを提供しましょう。読者は記事で説明されている概念を実際に使ったり、実験したりしてみることで、脳内に情報を強く結びつけることができます。

用例はライブサンプルのように記事に直接含めることもできますし、リンクすることもできます。もしそういった価値のある教材の作成に興味があるなら、 How to create an interactive learning exercise の記事を読んでみてください。

もしアクティブラーニング教材へのリンクを提供できない(知らない・時間がなくて作れない)場合、  タグを記事に追加してください。そうすると他のコントリビューターが、アクティブラーニングを必要とする記事を見つけやすくなって、ひょっとしたら見つけ出すのに役立つでしょう。

実習: 別な要素の選択 をインタラクティブな実習教材のサンプルです。また、 Active learning: Playing with scope はファイルをダウンロードし、編集するステップを踏みながら学んでいくような、別のスタイルの実習サンプルとして参考になります。

ステップ 6: 記事のレビューを受け、ナビゲーションメニューに追加する

記事を書き終えたら、我々が確認とレビューを行ない、改善点を提案できるように教えてください。再掲になりますが、連絡を取るための最善の方法は連絡方法の節をご覧ください。

記事を完了するためのもうひとつのタスクは、その記事を学習エリアのメインナビゲーションメニューに追加することです。このメニューは、編集するのに特別な許可が必要な LearnSidebar macro によって生成されています。そのため、追加するには我々のチームにご連絡ください。

メニューは少なくとも、あなたの記事には追加すべきです。 — マクロの {{LearnSidebar}} をページ最上部の段落に加えましょう。

おすすめの記事

何か記事を書きたいけど、何を書けばいいか分からないでしょうか?

学習エリアのチームは書くべき記事のアイデアを Trello のボードで管理しています。好きなものを選んで取りかかってください!

 

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

このページの貢献者: wbamberg, Uemmra3, bakunyo
最終更新者: wbamberg,