アドカレの時期なので書き出してみました。
自戒を込めての備忘録なので、語気が前のめりになっちゃってる部分はご容赦いただけると幸いですm(_ _)m
もくじ
- ドキュメントを書くつもりでまとめる
- 最初に「この記事で実現できること」を見せる
- 個人の感想やジョークを入れない
- 極端に固い文章にしない
- メイン話題の解説に「こちらを参照」をできれば入れない
- 文章だけで画面が埋め尽くされないよう気を付ける
ドキュメントを書くつもりでまとめる
- この記事で実現できること
- 手順概要
- 手順１、２、３...
- 結果
- まとめ・課題・今後の抱負
という構成以外になることはほとんどないはず。
最初に「この記事で実現できること」を見せる
この記事を読むとこういうことができるようになる・これが解決する・・・ということがわからないと、読む時間を割きたくない。
技術記事を読みに来る人は大抵何かに困ってて、Google検索に引っかかった大量の情報から潜ってきてる＝ストレス溜まってる
なので、記事リンク踏んでからそこそこ読み進めないと目的の情報が得られるかわからない状態だと、キレちゃう。
「記事で実現できること」をスクショやGIFで見せられるならそれを冒頭に載せる。
なければ「○○○をできるようにしてみました」「○○○という問題を×××で解決しました」を簡潔に書く。
「はじめに」みたいな単元作って２〜３行に収められると良さげ。
「なぜこの問題に向き合ったのか」などの経緯や、「この技術はどれほど素晴らしいか」みたいなアピールもとりあえず冒頭にはほぼ必要ないです。それらはまとめに全部寄せてとか、手順説明でどうしても必要ならそのタイミングで最低限の文量で入れましょう。
個人の感想やジョークを入れない
知りたいのは技術情報であって、記事を書いてるあなたではありません。
前述のとおり記事リンク踏んだ時点で結構ストレス抱えてるので、無駄話は控えて必要なことだけ描くのが好ましいです。
自分の色を出したければTwitterなりブログなりに書きましょう！
極端に固い文章にしない
一方で無闇に正しい日本語にこだわったりすると、それはそれでやはり読むのに時間がかかってストレスになりそうです。
そこそこ仲が良い先輩に説明するくらいのテンションがちょうどいいかなと思います。
また、誤解を減らすために補足を入れたり例外ケースについて説明したりしたくなることも多いと思いますが、それも読む時間を増やしてしまう原因になるので、「まとめ」に入れるか、まとめの後に「補足」みたいな節を作ってそこに寄せるといいと思います。
メイン話題の解説に「こちらを参照」をできれば入れない
何かに困ってて、Google検索でやっとたどり着いた（であろう）記事を頼って読んでるのに、そこからさらに別記事に派生して読まないと理解できない・・・ってなると割と挫けます。
とはいえ何かの情報を参照しないことは少ないと思うので、参照先は載せつつ、その記事の理解に必要最低限の情報は記事内で簡単に説明するのが誠実かなと思います。
文章だけで画面が埋め尽くされないよう気を付ける
文章だけで画面がバーーーーッと埋まってるとやっぱり読む気失せます。
画像・コードブロック・テーブルなどを程よく入れて、ぱっと見の印象にメリハリつけるようにすると、同じ文量でも挫けずに読み進められるように思います。（ラノベの挿絵みたいな感覚かもしれない）
さいごに（宣伝）
こんな記事を書いてます。
ここに書いてることが完璧に実践できてる自信はないですが、もし面白そうだなと思ったら読んでもらえると嬉しいです！