技術ブログの書き方|作ったもの・試したことを再現できる記事にする手順
三橋竜彰・
「自分で作ったツールの話を記事にしたいのに、何から書けばいいか分からない……」
「エラーを解決した手順を残したけれど、半年後に読み返したら自分でも再現できなかった」
「技術ブログの書き方を調べると、会社の技術ブログの話ばかりで、ひとりで書く自分に合うのか分からない」
ひとりでサイトやツールを作りながら、その記録を記事にしたい方に向けた記事です。
先に答えを書くと、技術ブログは、読んだ人が同じ結果にたどり着けるかで決まります。そのために、書き始める前に4つの記録を残し、記事では「結論・環境・手順・つまずき・結果」の順に並べます。
しかし、作業が終わってから思い出して書くと、バージョンやエラーの文面が抜け落ちます。そして抜けた所こそ、読んだ人がつまずく所です。
この記事では、次の3つを整理します。
- 書く前に残しておく4つの記録
- 技術ブログの記事の並べ方
- 読んだ人が再現できるかの確かめ方
読み終える頃には、次に試したことを、そのまま記事に起こせる準備が分かります。
技術ブログとは、作ったものや試したことを、読んだ人が同じようにできる形で残す記事です
技術ブログとは、自分が作ったものや試したことを、手順と結果つきで残す記事です。読む人の多くは、同じ作業の途中で手が止まり、検索から来ています。
ふつうのブログの記事と違うのは、読んだ人が手元で同じ作業をする点です。手順が1つ抜けているだけで、その人の作業は止まります。
Google も、良いコンテンツかを自分で確かめる問いの1つに「実体験や深い知識」を示しているかを挙げています。自分で手を動かした記録は、それだけで材料になります。
| 違い | ふつうの記事 | 技術ブログ |
|---|---|---|
| 読む人がすること | 読んで判断する | 読みながら同じ作業をする |
| 抜けると困るもの | 結論 | 環境・手順・エラーの文面 |
| 古くなる所 | 制度や料金 | バージョンや画面 |
この違いがあるので、書く前の準備が、ふつうの記事より大事になります。
書く前に残すのは、環境・手順・つまずき・結果の4つです
書く前に残しておくのは、環境・手順・つまずき・結果の4つです。作業しながらメモに残し、記事はそのメモから組むのが順番です。
作業が終わってから思い出すと、うまくいった手順だけが残り、途中で失敗した所が消えます。読んだ人が一番知りたいのは、その消えた所です。
以下の4つを、作業の途中で書き留めます。
- 環境: OS、使った道具の名前とバージョン、作業した日付
- 手順: 打ったコマンドや押したボタンを、順番どおりに
- つまずき: 出たエラーの文面をそのまま、そのとき試したこと
- 結果: 最後にどうなったか(動いた・途中でやめた、のどちらでも)
エラーの文面は、要約せずにコピーして残します。読む人は、その文面で検索してたどり着くからです。
うまくいかなかった試みも、記録としては価値があります。次は、この4つを記事の中でどう並べるかです。
記事は、結論・環境・手順・つまずき・結果の順に並べます
技術ブログの記事は、結論・環境・手順・つまずき・結果の順に並べます。最初に結論を置くのは、読む人が「自分の状況と同じか」を先に判断できるようにするためです。
書く前の4つの記録に、冒頭の結論を足した形です。見出しにすると、次のようになります。
| 順 | 見出しの例 | 書くこと |
|---|---|---|
| 1 | この記事で分かること | どんな問題が、どうなったかを2〜3文で |
| 2 | 試した環境 | OS・道具・バージョン・日付を箇条書きで |
| 3 | 手順 | 番号付きで、1つの手順に1つの操作 |
| 4 | つまずいた所 | エラーの文面と、試して直ったこと・直らなかったこと |
| 5 | 結果と、残った課題 | 最後の状態と、まだ分からないこと |
手順は番号付きのリストで書き、1つの番号に1つの操作だけを書きます。2つの操作をまとめると、読む人がどこで止まったかを言えなくなります。
見出しの立て方そのものは、ブログの書き方|書く前に決まる3つと、記事の組み立てにまとめています。ここでは技術ブログに特有の点だけを扱いました。
ほかの人が作ったツールの画面を載せるときの考え方は、ブログの画像の引用にまとめています。並べ方が決まったら、最後は再現できるかの確認です。
公開する前に、メモを見ずに記事だけで再現できるかを確かめます
公開する前に、作業のメモを閉じ、記事だけを見て最初から手順をなぞります。途中で止まる所があれば、そこが書き足りない所です。
自分で書いた記事は、頭の中で抜けを補って読んでしまいます。記事だけで手を動かすと、その補いができなくなり、抜けが見えます。
以下の4つを確かめます。
- 環境の節に、作業した日付とバージョンがあるか
- 手順の番号を飛ばさずに、最後までたどり着けるか
- エラーの文面が、画面に出たとおりに書いてあるか
- 「うまくいかなかった試み」も書いてあるか
手元で新しい環境を用意できるなら、そこで一度なぞるのが確実です。用意できないときは、記事を読み上げながら手順を指でたどるだけでも、抜けは見つかります。
確かめたあとの記事も、道具のバージョンが上がれば古くなります。最後は、公開したあとの扱いです。
公開したあとは、変えた所と日付を本文に残して直します
道具のバージョンが上がって手順が変わったら、本文を直し、変えた所と日付を本文に書き残します。読んだ人が「いつの情報か」を判断できるようにするためです。
Google は、自己評価の問いの中で、内容を実質的に変えないまま日付だけを変えていないかを挙げています。日付を新しくするのは、本文を直したときだけにします。
直すときは、以下の順で進めます。
- 新しいバージョンで手順をなぞり、止まる所を見つける
- その手順だけを書き直す
- 冒頭か該当の節に「○年○月に、○○のバージョンに合わせて手順3を直しました」と書く
- 環境の節のバージョンと日付を新しくする
古い手順を消すか残すかは、まだ古いバージョンを使う人がいるかで決めます。迷ったら、古い手順を折りたたみや別の節に残しておくと親切です。
次に書くネタに迷ったら、ブログのネタの探し方で、書いた記事と読者の検索から次の1本を探す方法をまとめています。
よくある質問
技術ブログは、専門家でなくても書いていいですか?
書いて大丈夫です。Google も、すべてのコンテンツに専門知識が必要なわけではない、と説明しています。自分で試した手順と結果を、そのまま正確に書くことが大事です。
うまくいかなかったことも記事にしていいですか?
記事にして大丈夫です。どこまで試して、どこで止まったかを書きます。出たエラーの文面も添えれば、同じ所で止まっている人の助けになります。
作業した日付は、なぜ書くのですか?
道具の画面や手順は、バージョンが上がると変わるからです。日付とバージョンがあれば、読む人は自分の環境と比べて、その手順が使えるかを判断できます。
コマンドや設定は、画像で載せてもいいですか?
文字で載せるのがおすすめです。読む人がコピーして使えるうえ、エラーの文面は検索にも使われるからです。画面の位置を見せたいときだけ、画像を添えます。
1本の記事に、どこまで書けばいいですか?
1本の記事には、1つの問題とその結果だけを書きます。途中で別の問題が出てきたら、その問題は別の記事にしてリンクでつなぐのが読みやすい形です。
まとめ
技術ブログは、読んだ人が同じ結果にたどり着けるかで決まります。
- 書く前に、環境・手順・つまずき・結果の4つを、作業しながら残す
- 記事は、結論・環境・手順・つまずき・結果の順に並べる
- 公開する前に、メモを閉じて記事だけで手順をなぞる
- 直したときは、変えた所と日付を本文に残す
次に何かを作ったり試したりするときは、作業を始める前にメモを1枚開いておくところから始めてみてください。