はじめに
エンジニアの仕事は、コードを書くことだけではありません。実は、文章を書く時間も相当なウェイトを占めています。
- Pull Requestの説明
- 技術ドキュメント
- 障害報告書
- メールやSlackでのコミュニケーション
新人エンジニアの頃、私も文章を書くのが苦手でした。レビュアーに意図が伝わらなかったり、ドキュメントが分かりにくいと指摘されたりすることが続いていました。
そんな時、先輩エンジニアに勧められたのが「バカだと思われない文章術」という本です。エンジニアの実務に直結する実践的な内容ばかりで、すぐに使えるテクニックが詰まっています。
以下、本で紹介されている中でも特に大事なポイントをいくつか紹介します。
1. 失礼なことを書かない
NG例
先ほど送ってもらったファイルに不備があり、こちらでは開くことができませんでした。
きちんと確認されたのでしょうか。至急送り直してください。
問題点: 相手を責める口調になっている
OK例
先ほどお送りいただいたファイルを開こうとしたところ、こちらのPCで開くことができませんでした。
恐れ入りますが、ファイルに不備がないかご確認いただけますでしょうか。
もし不備があるようでしたら、改めて正しい状態のファイルをお送りいただけると助かります。
お手数ですが、よろしくお願いします。
ポイント:
- 事実を客観的に伝える
- 相手を責めず、改善案を示す形にする
- 余計な詮索をしない
2. 引っかかるような事は書かない
NG例
ある特別な事情により、このAPIは廃止予定です。
OK例
このAPIは廃止予定です。
ポイント: 「特別な事情」のような曖昧な表現は読み手の気を散らす。本筋に関係ない情報は省く。理由が重要なら別途明記する。
3. 略語は()で補足する
NG例
CCを使ってAAを作成しました。
OK例
CC(ClaudeCode)を使ってAA(ASCII Art)を作成しました。
ポイント: チームの共通認識になっている略語でも、新人や他チームが読む可能性があるドキュメントでは初出時に補足する。
# 初出時は必ず説明を
ORM（Object-Relational Mapping）を使ってDBアクセスを抽象化します。
DI（Dependency Injection）コンテナで依存関係を管理します。
# 2回目以降は略語のみでOK
ORMのクエリを最適化しました。
DIの設定を変更しました。
4. 接続詞は省略できる
NG例
バグを発見した。そしてログを確認した。だから原因が特定できた。
でも修正は難しかった。むしろ設計から見直す必要があった。
OK例
バグを発見し、ログを確認した。原因が特定できた。
しかし修正は難しく、設計から見直す必要があった。
ルール:
- 順接の接続詞（だから、それで、そして）→ 省略可能
- 逆接の接続詞（でも、しかし）→ 省略不可
5. リズムが大事 - 音読のすすめ
重要な決断や結論は短い文で言い切る
NG例
今回の調査結果を踏まえると、パフォーマンス改善のためには
データベースのインデックスを見直す必要があるのではないかと考えられます。
OK例
データベースのインデックスを見直すべきだ。
実践方法:
文章を書いたら必ず音読する。スムーズに読めて、意味がすっと入ってくればOK。
6. 否定文より肯定文
NG例
pullしないまま作業を始めないでください。
OK例
pullしてから作業を始めてください。
ポイント: 否定文は「何をすべきか」が伝わりにくい。肯定文で「正しい行動」を示す。
7. 「が」は逆接でしか使わない
NG例
先日PRのキャッシュ戦略を見直しましたが、レスポンス速度が改善されて良さそうでした。
読み手は「が」を見ると逆接（反対の内容が来る）を期待する。「キャッシュ見直した→でも改善されてない？」と一瞬混乱する。
OK例
先日PRのキャッシュ戦略を見直しました。
レスポンス速度が改善されて良さそうでした。
ポイント: 「が」は逆接のときのみ使う。並列・順接の場合は文を分ける。
技術記事・ブログを書く人へ
ここからは、日常業務だけでなく技術記事やブログを書く人に特に役立つテクニックを紹介します。
8. 伝えたいことは言い切る
NG例
このライブラリが最適で有名です。
ただ、本当に最適かどうかはOSやその他の環境、ロジックによって変わると思います。
また、有名といいいましたがエンジニア100人のアンケートで70人が知っていると答えただけで、逆に30人は知らないライブラリなのでそこまで有名ではないかもしれません。
さらにアンケートもXでの投票になるため、本当は知らないけど知っていると嘘で言っている可能性もあり信憑性が低いものとなっています...
OK例
このライブラリが最適で有名です。
このライブラリを導入するとパフォーマンスが改善されます。
細かい注意事項が必要なら最後に別途書けばいい。メインの主張は堂々と言い切る。
9. 一般論を軽々しく書かない
NG例
最近のエンジニアはドキュメントを書かない。
OK例
私のチームでは、ドキュメントが更新されないまま実装だけ進むことが多い。
ポイント:
- 一般論ではなく体験談として書く
- 「みんな」「いつも」などの全称表現を避ける
- 自分が見聞きした範囲であることを明示する
個人的に特に大事だと思ったこと
この本から学んだ中で、実務で特に意識すべきポイントを3つ挙げます。
1. 「音読」の習慣化が最強
文章を書いたら必ず音読する。これだけで文章の質が劇的に変わります。
長い技術ドキュメントを書いた後に音読すると、「あれ？ここ意味がわからない」「この接続詞いらないな」と気づく箇所が必ず出てきます。声に出すことで、読み手の視点に立てるからです。
PRの説明文やREADMEなど、他の人が読む文章は必ず音読する習慣をつけましょう。
2. 「言い切る」勇気を持つ
エンジニアは正確性を重視するあまり、「〜かもしれません」「〜と思われます」と保険をかけがちです。
本当に伝えたいことは堂々と言い切るほうが説得力があります。細かい注意事項や例外は別途補足すればいい。メインの主張は自信を持って断定しましょう。
# NG
このアプローチが最適かどうかわかりませんが...
# OK
このアプローチを採用します。理由は以下の通りです。
3. 「が」の使い方に気をつける
「が」を並列の意味で使うと、読み手は逆接を期待して混乱します。
技術文書では特に論理的な流れが重要なので、「が」は逆接のときだけ使うと決めると、文章の論理構造が明確になります。
まとめ
文章力はエンジニアにとって重要なスキルです。以下のポイントを意識するだけで、格段に読みやすく、説得力のある文章が書けます。
- 相手を責めない - 事実を客観的に伝える
- 余計な情報を入れない - 本筋に集中させる
- 略語には補足を - 初出時は必ず説明
- 順接の接続詞は省略 - 文章をスッキリさせる
- 音読する - リズムの良し悪しがわかる
- 肯定文を使う - 柔らかい印象になる
- 「が」は逆接のみ - 誤解を防ぐ
- 言い切る - 自信と説得力が生まれる
- 体験談として書く - 一般論より説得力がある
最後に
これらのテクニックは、ドキュメント作成だけでなく、日々のコミュニケーション全般に活用できます。
特に音読を習慣化するだけで、レビューコメントやドキュメントの質は確実に上がります。チームメンバーに「わかりやすい」と言ってもらえる文章を書けるエンジニアは、それだけで信頼されます。
良い文章は良いコードと同じく、他の人に価値を提供します。自分の考えを正確に伝える力は、エンジニアとしてのキャリアにおける大きな武器になります。
できることから一つずつ実践してみてください。
参考文献
本記事で紹介したのはほんの一部です。元の本にはまだまだ多くのテクニックが載っているので、ぜひ読んでみてください。