テクニカルライティングを上達させるには期待値を下げるべきです [翻訳記事]

1. 文章を書くことはエンジニアの必須スキル

   • テクニカルライティングは、コミットメッセージからドキュメント作成まで、あらゆるレベルのエンジニアにとって不可欠です。
   • 文章を書くのが得意かどうかの違いは、業務効率や組織内のコミュニケーションに大きな影響を与えます。

2. できるだけ簡潔に、短く

   • 読者は文章に多くの時間をかけません。
   • アイデアを1文で伝えられるなら、そうしてください。
   • あえて細部を省略することが、むしろ利点になることもあります。
   • 重要な内容は文章の前半、最初の文やタイトルに入れましょう。

3. 期待値を現実的に設定する

   • 技術的な文章を丁寧に読み込み、完全に理解してもらえると期待しないでください。
   • エンジニアリング組織では、混乱や理解度の差は普通のことであり、文章だけで全員を同じ認識にすることはできません。
   • 期待値を下げることで、かえって効果的なコミュニケーションになります。

4. 文章の目的は明確な核心を伝えること

   • 「設定追加は複雑だ」のような非常に単純な要点を、広いチームに伝えることが最優先の目標です。
   • 技術的に完全な理解を導くことよりも、最低限のコンテキストを提供して信頼を得ることが重要です。

5. 実際に期待できる効果

   • 文章の受け手は、たいてい書き手より背景知識が不足しています。
   • 広い対象には単純なメッセージの伝達が、ごく少数には複雑な内容の明確な伝達が可能です。
   • 核心だけを押さえて示すことだけでも、大規模な組織では大きな違いを生みます。

6. 明確な思考が明確な文章を生む

   • 理解が不十分なテーマは、圧縮して書くのが難しいものです。
   • 不確実性を認め、明確に説明できる部分に集中してください。

7. 失敗しがちな点と推奨事項

   • 細かすぎる情報を伝えることに執着しないでください。
   • 伝えたい内容は、1文、1段落、1ページという単位で少しずつ要約し、核心を先に伝えましょう。
   • 技術的な背景知識がほとんどない人たちに対しても、大きな文脈を伝えること自体に価値があります。

[yeobi222]

理解してもらうための補足説明をどう入れるべきかが、いちばん悩ましいところですよね。
意思決定者がその分野の門外漢だったり…

[girr311]

技術文書だけでなく、大半の文書にも当てはまる内容ですね。