概要
技術ブログを書くための心構えや使っているツールを紹介します。
心構え
まずは意識していることから
人に説明できなきゃ理解してるとは言えない
- 教えることは二度学ぶこと
- 人に教えるにはｎ倍理解してないといけない
など色々いい方はありますが、誰かに説明するためには一通り理解している必要があります。
なので理解度を上げるためにもアウトプットした方が良いとモチベーションを持たせます。
未来の自分も読者
人は忘れる生き物なので、その時点では詳しくても時を経るとすっかり忘れて同じ問題にハマります。
なので内容を忘れた未来の自分でも分かるよう、できる限り分かりやすく、かつハマったところはちゃんと書き出すようにします。
１ヶ月後くらいに見返しただけでも「あれ？これどういうこと？」となったりするので、そういった時は分かりやすい説明に修正したりします。
あとはてなブログはブックマークやスターが付いた時に通知が来るので、その時に読み返して復習＆分かりやすさチェックしたりしています。
忘れる前に書く
上と似てますが、膨大なインプットを常に記憶していくことは無理なので忘れる前に書くようにします。
落ち着いたら書こう、だとインプットした当時の知識レベルに比べかなり質が落ちてたりするので、なるべく早めに書きます。
逆にアウトプットしたら（書いたら）もう忘れて良いやくらいの心構えが良いですね。
図を描く
- 自分の頭の中を整理する
- 全体像を把握する
- 後で読み返した時にすぐ理解できるように
といった目的でなるべく図を描くようにします。
逆に知らない技術をキャッチアップする際は画像検索を使って調べたりしています。
参考・情報のソースを貼る
著作権的な意味もありますが、リンクがあると後から見返したときに非常に助かります。
「ここどういうことなんだっけ？」と理解が足りない時に参考になったソースを読み直すことで「あぁこういうことだったのか」とキャッチアップしやすくなります。
またメソッドなどにドキュメントのリンクを貼ったりすると「他の使い方はどうなんだっけ？」といった深堀りをする際にスムーズに進められるのでおすすめです。
既に良ドキュメント・良記事があっても書く
既に良ドキュメント・良記事があっても、もし自分の中で感じたこと・発見があれば参考リンクを貼った上で書くようにしています。
その発見が他の人（未来の自分を含む）にとってプラスになるかもしれないですし、書くことで記事を読んだだけでは気づかなかった点にも気づいたりするためです。
あと良記事に限って気づいたら消えてたりするので、知見が失われないようにという意味でも書いたほうが良いです。
再現性
技術記事でよくあるのが「バージョンが違うから記事で紹介されている方法ではうまく行かない」パターンです。
うまく行かない原因が分からない状態で、自分の手順が間違っていたのかなど１からやり直すのは大変です。
環境差異が明示されていればその違いが原因かもと当たりをつけることができますし、そもそも最初の段階で「バージョンが異なるからどこかで違うところが出てくるかも」と心構えができます。
なのでできる限り検証した際の環境を書くようにしています。
プライドは持たない
この業界は知識が武器なので、そこそこの武器（知識）を持ってると
- 今までこんな基礎的なこと知らなかったなんて…
- 後輩の方が詳しかった…
- 間違ってたときのマサカリが怖い…
とプライドが邪魔して書くのを躊躇ったりします。
が、そのプライドは自身の成長を邪魔するだけなので割り切って書きます。
間違えたら修正すればいいですし、更に詳しいことを教えてもらったら加筆すればいいのです。
ツール
以降はツールの紹介です。
僕が技術ブログを書くときは大体これらのツールを使います。
Skitch
概要
Evernoteが出してる画像編集ツール
自分の使い方
基本的にスクリーンショットをサクッと編集したい時に使います。
- コメント付ける
- 矢印や丸、四角でフォーカスさせる
- 個人情報にモザイク
例
diagrams.net (draw.io)
概要
ブラウザ上でフローチャートからUML図、アーキテクチャ図など何でも描けるツールです。
自分の使い方
- アーキテクチャ図
- タイムライン
PlantUML
概要
Diagrams as Codeを実現できる言語？です。
VSCodeにもプラグインがあるのでプレビューを表示しながら書けます。
自分の使い方
- シーケンス図
- ユースケース図
- クラス図
- オブジェクト図
- 状態遷移図（ステートマシン図）
あたりを書く時によく使います。
GIPHY Capture
概要
画面をキャプチャしてgifやmp4を生成できます。
自分の使い方
画像だとどうしても分かりづらいような操作だったりフローについてはこれを使って一連の流れをキャプチャします。
まとめ
技術ブログを書くための心構えやツールを紹介しました。
最初はツール紹介の目的で書き始めましたが気づいたら心構えの方が多くなってました。
技術ブログやドキュメントを書く際の参考になれば幸いです。
