開発ドキュメントなどの技術記事を分かりやすく書くための方法を「開発ドキュメントの書き方」に公開しました。以降はこちらもご覧ください。
技術ブログの記事やドキュメントは、構成や書き方しだいでわかりやすさを大きく改善できます。筆者はこれまでに技術書の執筆や技術ブログの運営、ドキュメントの執筆をとおしてたくさんの記事を書いてきました。
この経験をとおして得た、技術記事を書く上でおさえるべきポイントについて示します。
テクニカルライター。元エンジニア。共著で「現場で使えるRuby on Rails 5」を書きました。プログラミング教室を作るのが目標です。
この記事の目的
対象となる読者はエンジニアの方で、とくに「技術記事をどう書けばいいかわからない、伝わるか不安」という方を想定しています。技術ブログの記事やドキュメントといった技術記事を書くときの指針となるポイントについて示します。
この記事をとおして、よりわかりやすい記事を書けるようになることを目的とします。
技術記事とは
技術記事とは技術ブログの記事やドキュメントなど、書き手の経験をもとにした体系的な知見や、課題とそれに対する解決策を示したものなどをいいます。書き手自身の知識の定着やメモになるのはもちろん、読んだ人に技術的な知見を提供する役割をもちます。
また「自分がその知識をもっている」ということを周知することでブランディングにもなります。
背景
前章のとおり技術記事は書き手にも読み手にもメリットのある重要な文書です。記事の存在だけで十分に価値があるといえます。
一方で「用語が難しい」「再現性がない」「いつ書かれたものかわからない」など、読む上で理解しづらい記事があるのも事実です。せっかく書くならわかりやすい記事を書けるようになろう、というのがこの記事の主旨です。
ポイントをおさえることでできること
この記事に示すポイントをおさえることで、次のことができるようになります。
- わかりやすい記事になる
- 読み手が記事を読むべきか、読まなくていいかすぐ判断できる
- 再現性があり、いつでも何度でも参照可能なリソースになる
ユースケース
この記事に示すポイントは、次のような文書を書くときに有用です。
- 技術ブログの記事: たとえばデザインパターンについての記事や、バグとその解決策について示した記事
- ドキュメント: チームで採用したインフラアーキテクチャの構成図と、それにいたった背景
技術記事を書く上でおさえるべきポイント
技術記事を書くときのポイントを「構成」「書き方」「記事の表示方法」の3つにわけて示します。以下は体系的な知見を技術記事にするときの例ですが、バグに関する記事などほかのものにも応用できます。
構成について
ひとつのことのみを書く: ひとつの記事に複数の本題があると長くなりわかりづらくなる。記事を分けて参照するようにする。
結論を最初に書く: 技術記事は読みものではなくインプットや課題解決が目的。タイトルに対するアンサーがなかなかこないとわかりづらくなる。もちろん例外として月刊誌のような読みものもある
目的や対象を書く: 誰にどういう課題があって、この記事でなにを示すか、読むとどうなるかを書く。ここで書いた読者対象にあわせて用語を使い分ける。
前提をそろえる: 「アーキテクチャ」でもインフラなのかソフトウェア設計なのか、文脈によって変わってくる。認識がずれないよう、はじめに説明する。
再現性をもたせる: ソフトウェアならバージョン、外部APIなら投稿日や更新日など、記事にある条件なら必ず再現するようにする。
書き方について
アウトラインを書き、推敲する: いきなり書きはじめると構成がまとまらなくなる。アウトラインで全体像を描き、推敲でブラッシュアップした上で書きはじめる。
文を短く切る: ひとつの文が長いと読みづらくなる。ひとつひとつの文を短くしたり、不要な表現を削除したりする。
平易な表現にする: 想定している読者の技術レベルにあわせて、むずかしい単語を別の表現に変えたりする。
記事の表示方法について
投稿日、更新日を表示する: 技術の変化ははやいため、いつ書かれたかはとても重要な情報になる。単に表示するのではなくわかりやすく表示すべき。
著者を表示する: その情報は信頼できるのかの判断材料になる。また記事の内容に問題があったときにコンタクトするためにも重要な情報になる。
目次を表示する: 全体でどれくらいの長さか、どんな構成か、読むべきかどうかをなんとなく把握できる。
備考
筆者自身のストーリーがあった方が伝わりやすい、よみやすいこともあります。上記ポイントをベースに肉づけしていくといいと思います。
また、技術記事の書き方についてはGoogleが「Technical Writing」として文書を公開しています。あわせて読むとよりわかりやすい記事を書くことにつながります。
まとめ
この記事では、技術記事をわかりやすく再現性のあるものにするためのポイントについて示しました。技術記事には価値があります。ポイントをおさえるのもそうですが、まずは書いて公開すること、そしてなにより消さないことが大切だと思います。
