技術文書を書く際に注意すること

昨日、永江一石さんという著名なマーケターの方の文章術の記事がSNSで回覧されてきたわけです。

秘伝?? 文章が巧くなる方法について

読みやすい文章を書くという点では、”てにおは”や"です・ます”を揃えるという基本から、主語・述語の関係を整える。極力、文章を短めにして言い切りの形にするなどの作法があるわけでして、文章のレビューをする際には、自分でも小声で音読することは多いです。音読重要。

さらに、技術屋向けの文章というのは、正確に意志疎通を行うという目的があるため、誤解を招くような表現を避ける工夫が必要になります。読み手に対して、ロジックを明確に提示したり、複数の解釈を与えない文章が必要になってきます。そうでないと、例えば要件定義や設計において、完成後に「実はこんなつもりじゃなかったのに・・・」という事故が起こりうるわけです。

  • 結論ファースト。理由や詳細事項は後に列挙する。
  • ぼかした表現に逃げずに、できるだけ明確に書く。行間を読ませない。
  • 自分の「意見」と「事実」をごっちゃにしない。
  • 事実を記述する文はできるだけ名詞と動詞で書き、主観に依存する修飾語を混入させない。
  • 表記は統一する。特に多義語は注意(例えば「クライアント」は、「お客様」にも取れるし「利用者が使う端末」「利用者が使うアプリケーション」など、いろいろな意味で解釈できる。)

今日、お客様とのミーティングの際に、表記をめぐっての誤解がありまして、先方の意図の確認にずいぶんと時間を使ってしまいました。自分への戒めも兼ねてのメモです。

Tips

Posted by tomi