はじめに
「わかりやすいドキュメント書けていますか？」
「文章をわかりやすくうまく書けていますか？」
私自身、これがとても苦手です！
この記事では、経験をもとに、テクニカルライティングの基本をあらためて書籍で学び直し、また先輩からの指摘もいただきながら、それを元に自分なりに改善した経験を共有します。
この記事は、以下を参考にしています！
※Notionでドキュメントを書くことを想定しています！
対象読者
- ドキュメント作成が苦手な若手エンジニア
- テクニカルライティングを学びたいエンジニア
🤔 なぜエンジニアにテクニカルライティングが必要なのか？
始めは、エンジニアにテクニカルライティング能力って必要なの？と思っており、最低限内容が網羅できているドキュメントがかければいいでしょというスタンスでいました。
しかし、実際インターンから1年半ほどエンジニアとして働いていると、要求要件の検討の際にドキュメントを書いて提案することや、今後チームにJOINする人に向けたドキュメントなど、コードを書くことと同じぐらいの頻度で書くことが多く、大切なことが身に染みてわかりました。
自分の失敗で言うと、仕様検討の際に、理解しにくいドキュメントを作成してしまい、PdMやチームメンバーが理解するのに多くの時間を要してしまうことが多々ありました。結果、意思決定に時間がかかり、自分の持っているタスクが遅延し、結果的にプロジェクト全体が遅延することもありました。🥹
🙌 テクニカルライティングを習得するメリット
一言で言うと、テクニカルライティングができると、意思決定の高速化、チーム全体の生産性向上などがスムーズになると思っています。
まだまだ多くメリットはあると思います！
私は、要求や要件をまとめ、設計し提案する時に、ドキュメントをまとめ提案していますが、ドキュメントの質が低いことによって、以下のような経験をしたことがあります。
- 読み手が異なる解釈をした
- 読み手が理解するのに時間がかった
- 情報がうまく整理できておらず漏れが発生した
これにより、仕様についての詰めが甘く、考慮漏れが多く、結果的にプロジェクト自体に影響が生じてしまいました。
テクニカルライティングを習得していれば、プロジェクトがスムーズに進行していたのではないかなー、と感じています。
このように、エンジニアにとって「わかりやすいドキュメント作成」はとても重要なスキルだと考えています！
💪 テクニカルライティングのポイント
テクニカルライティングを改善するために、以下のポイントに注意しました。これらは参考書籍の第２章から学んだ内容です。
以下のポイントを取り入れた結果、ドキュメントが大きく改善されました。
- 必要な人にだけ読ませる
- 構造化・階層化を意識できたドキュメント
- 表記揺れを防ぐ
- 読者の知識を考慮する
- 1つの段落で1つのことについて書く
- 誰でも同じ解釈ができる文章
1. 必要な人にだけ読ませる
- 読者層を明確にし、誰が読むべきかを明示する。
- ドキュメントを読むことで、読者にどう行動してほしいのかを示す。
2. 構造化・階層化を意識できたドキュメント
- 情報を階層化し、大枠から細かい情報へと整理する。
- 文は短く、読みやすい長さにし、一口で読める分量にまとめる。
3. 表記揺れを防ぐ
- チームでは、ユビキタス言語で定めているものが多いので、それに従って表記揺れを防ぐ。
- 接続詞をできるだけ減らし簡潔に表現する。
4. 読者の知識を考慮する
- 読者が既に知っている情報から書き始め、次に新しい情報を提示する。
5. 1つの段落で1つのことについて書く
- 1段落につき1つのことを述べる。
- 脳が処理できる情報の数を意識する。
6. 誰でも同じ解釈ができる文章
- 曖昧さを排除し、誰でも同じ解釈ができるよう明確に表現する。
😭 過去に書いたドキュメントの改善
ここからは、自分が過去に書いたドキュメントを振り返り、その問題点を分析しました。
うつせないところが多くありますが、すみません！
過去に書いたドキュメント
自分が過去に書いたドキュメント
まあ、ひどいドキュメントですよねwww
改善したドキュメント
改善したドキュメント
👑 自分が感じたドキュメントを書くtips
いろんな人のアドバイスや、社内ドキュメントを読み漁って、感じた改善TIPSをまとめます！
- 結論・決定したいことファーストで書く
- 分量が多くなる場合、ドキュメント冒頭に要約のセクションを設ける
- 箇条書きは必要最小限に
- 目次を使う
- 情報を伝えるために、不必要かわからない時は、トグルに入れる
- テンプレートを用意する
- 見出しに背景色をつける
- リードやマネージャーなどのドキュメントを読む
- ドキュメントを書く工程と、読みやすくまとめる工程を切り分ける
1️⃣ 結論・決定したいことファーストで書く
結論を最初に提示するといった簡単に聞こえることですが、とても難しいですよね😭
ここができており、自分の認識と読み手の認識が揃ったならば、ドキュメントとして言うことはない気がします！
2️⃣ 分量が多くなる場合、ドキュメント冒頭に要約のセクションを設ける
結論・決定したいことファーストで書くとかぶるところがありますが、読み手は1から10まで、長いドキュメントを読むのは辛く感じます。
なので、冒頭に、要約のセクションがあれば、全体像や伝えたいことがある程度わかり、詳しい内容が知りたければ、その後読み進めると思います！
3️⃣ 箇条書きは必要最小限に
箇条書きが長くなると、どうしても読みにくくなってしまいます！💦
箇条書きのネストも深くなってしまうと、どうしても読みにくくなってしまいます！（if文と同じです！）
なので、必要最低限にしましょう！
4️⃣ 目次を使う
Notionの目次を利用すると、読者が全体像を瞬時に理解できると思います！
特に、分量が多くなる場合、要約と一緒に書くのが良いと思います！
5️⃣ 情報を伝えるために、不必要かわからない時は、トグルに入れる
人それぞれになるかもですが、情報を伝えるために、不必要か迷った時は、トグルに入れるようにしています！
別に読まれなくても、いいけど残しておきたい文ってありますよね？その文章などはトグルに入れています！
例えば、ドキュメントには、提案する内容だけを書き、自分の意思決定の背景や、会議で決まったことはトグルに入れるようにしています！
6️⃣ Notionでテンプレートを用意する
毎回読みやすいドキュメントを一から書くのは辛いです💦
そこで、テンプレートがあれば、大体各方針が決まり、進めやすいと思います！
Notionで、テンプレートを用意する方法は以下です！
7️⃣ Notionで見出しに背景色をつける
見出しはつける人多くて知っているよ！という方が多いのですが、
見出しに背景色をつけるとすごく見やすくなります！
8️⃣ リードやマネージャーなどのドキュメントを読む
社内のリードエンジニアやマネージャーなどのドキュメントをたくさん読み、たくさんマネをすることが良いドキュメントにつながると思います！
上のレイヤーの人は、その上の経営陣などに提案しているはずですそのドキュメントは、簡潔でわかりやすいドキュメントになっているはずです！
9️⃣ ドキュメントを書く工程と、読みやすくまとめる工程を切り分ける
自分は、ドキュメントを書く工程の時に、読みやすさを意識して書くと、不備が多いので、初めは、頭の中にある考えや伝えたいことなどを読みやすさを考えずに書き、最後に読みやすくまとめています！
また、読みやすくまとめる工程で、独自のドキュメントの読みやすさのチェックリストを用意するのもいいかもですね！
まとめ
テクニカルライティングは単に「文章を書くスキル」ではなく、情報を効果的に伝えるための重要なスキルだと思っています。
エンジニアとして、わかりやすいドキュメントを作成することで、チーム内外でのコミュニケーションを円滑にし、結果的にプロジェクト全体に貢献できるようになります。
この学びを今後の仕事に活かし、より良いアウトプットを目指していきます〜！💪👋
参考文献
PR
HRBrainでは一緒に働く仲間を募集しています〜！🙆
HRBrain文化を一緒に作っていきましょう！