技術文章は、知っていることを全部書く作業ではありません。読む人が、必要な判断や操作をできるように情報を並べる作業です。
最初に読者と行動を決める
| 文書 | 主な読者 | 読後の行動 |
|---|---|---|
| README | 初めて成果物を見る人 | 目的を理解し、動かすか判断する |
| セットアップ手順 | 開発へ参加する人 | 環境を再現する |
| 障害報告 | 利用者・関係者 | 影響と現在の状態を理解する |
| 設計メモ | 将来変更する人 | 判断理由を再確認する |
読者が違えば、説明する用語と省略できる前提も変わります。
結論を先に置く
悪い例:
昨日からいくつか確認を行い、ログも調査したところ、現在は復旧しています。
改善例:
現在は復旧しています。7月10日10:02〜10:14の間、ログイン機能を利用できませんでした。
読み手は、最初に「今使えるか」「自分に影響があるか」を判断できます。
手順には確認結果を書く
操作だけでなく、成功した時に何が見えるかを書きます。
npm install
npm run dev
ブラウザで http://localhost:4321/ を開き、トップページが表示されれば準備完了です。
確認結果がない手順は、読者が成功と失敗を判断できません。
一文と一段落を詰め込みすぎない
一文に前提、操作、例外、注意をすべて入れると、重要な条件を見落とします。一段落では一つの話題を扱い、例外や注意は別にします。
ただし、短い文ごとに改行しすぎると流れが切れます。文章の長さより、意味のまとまりを基準にします。
読者の視点で読み直す
- 初出の略語に説明があるか
- 必要なOSやバージョンが分かるか
- コマンドをどこで実行するか分かるか
- 失敗時の確認場所があるか
- 秘密情報を貼る指示になっていないか
- 古くなりやすい情報に日付があるか
最後に、自分が何も知らない読者だと仮定して手順を実行します。
参考リソース
次に読む記事
← 一覧に戻るPR
PR
