4-10 執筆におけるアンチパターン
最終更新
役に立ちましたか？
最終更新
役に立ちましたか？
役に立ちましたか？
執筆を進めていくなかで、どういう風に進めていったらまずいのか、また分かりにくい教材のパターンを紹介できればと思います。
おすすめしない執筆の進め方
分かりにくい教材の構成やパターン
意図と異なるマークダウンの利用について
おすすめしない執筆の進め方は主に3つあります。
実装しながら執筆する
執筆レビューの修正対応より先に執筆する
執筆スタイルガイドをあまり見ないで執筆する
1つずつ説明します。
教材で作成するアプリケーションを実装しながら執筆すると、途中でコードを変更したくなったときに、そのコードが教材で複数登場していれば、複数箇所修正しないといけなくなります。それは非常に手間です。なので執筆する前に教材で作成するアプリケーションを実装しましょう。
執筆レビューの修正対応より先に執筆を進めた場合、同じ修正を何度もする可能性があります。それは非常に手間だと思います。レビューが上がってきたら、まずレビューを確認しましょう。
執筆スタイルガイドは、Techpit がこれまで2年以上運営してきたなかの教材作成におけるノウハウになります。どういう構成にしたらいいか、どういう風にしたら分かりやすいかなど細かいところまで記載しています。執筆スタイルガイドを把握した上で執筆を進めていきましょう。
次に分かりにくい教材の構成やパターンを紹介します。
1つのコードブロックに対して実装のスコープが大きい
1ページの文量が多い
主語が曖昧になりやすい言葉を使用する
学習を進めていく際は、1つ1つステップバイステップで進めた方が分かりやすいです。逆に、1つのコードブロックに対して実装のスコープが大きくなると、コードを見る量、学ぶ量が多くなり、今自分が何をしているのか分からなくなります。人間そんなに一気に頭に詰め込むことはできません。
なので、できるだけステップバイステップで実装を進められるような構成を意識しましょう。
1ページの分量が多くなる場合、読むのが大変になります。Techpit は、Web上で学習をするため、1ページの文量が多くなればなるほどスクロールしないといけなくなるからです。また体験的にも達成感を味わいにくくなります。なので、1ページの文量は多くても10000字程度になるようにしましょう。
文章中の「〜〜を記載します」や「〜〜に変更します」といったコードやプログラムの操作に関わる動詞の現在形は
執筆者が解説のために行ったこと
教材として学習者が行わなければならないこと
というの2つの捉え方ができてしまいます。そのため学習者はその文章を読んだ際に自身がコードの操作をすべきかどうか悩んでしまいます。
これを防ぐため、学習者にしてほしいことは「〜〜を記載してください」や「〜〜に変更しましょう」などの依頼表現にしてください。同様に学習者が操作する必要はなく、解説のために執筆者が行ったことは「〜〜を記載しています」や「〜〜に変更しました」など過去形にしましょう。
意図と異なるマークダウンの使い方での執筆をされていることがあります。 「4-8 見やすい文章を書くためのマークダウンの書き方」にて紹介しているマークダウンの使い方に沿って執筆してください。
マークダウンのアンチパターンを紹介します。
引用は文章を他文献から文章を紹介する際に利用するもので、文章を強調するために利用するのは避けてください。見出しにはh1やh2タグ、強調には**通常の太文字**を使用するようにしてください。
斜体もアルファベットの協調として利用されることもあると思いますが、Techpit上では「太文字での強調」に統一できればと思います。
箇条書きは複数の項目を端的に列挙する際に利用してください。 文章で記述していても、全ての文章が箇条書きで1行ずつ記述されている場合、可読性が低くなってしまいます。
この画像は実際に全ての文章を箇条書きで記述した例です。
このように、段落がわかりづらく可読性が低くなります。
項目を列挙する場合のみに箇条書きや表形式を利用し、段落を分けたい場合は改行を用いて記述していただければと思います。
