開発ドキュメントの文章を推敲する方法

私はテクニカルライターとして働いていて、仕事では開発ドキュメントを、プライベートでは技術ブログを書いています。

文章を書いたら、基本的には公開する前に推敲をしています。ただ、推敲のやり方を自分の中で言語化できていませんでした。

この記事では、自分なりの推敲のやり方をまとめています。より読みやすい、分かりやすい文章にするきっかけになれば嬉しいです。

著者
Hiroki Zenigami

テクニカルライター。開発者向けのドキュメントを書いています。元エンジニア。共著で「現場で使えるRuby on Rails 5」を書きました。

目次

推敲とは何か

推敲とは、Wikipediaによると、

推敲(すいこう)とは、文章を何度も練り直すこと。

とあります。開発ドキュメントにおいては、「よりよい開発ドキュメントにするために、文章を何度も練り直すこと」だといえます。

例えば、文章の構成や表現方法を変えることが推敲にあたります。

校正・校閲との違い

推敲の他に、「校正」と「校閲」という言葉があります。この三つを比較すると、次のようになります。

種類目的効果
校正文字の間違いを直すマイナスを減らす
校閲情報の間違いを直すマイナスを減らす
推敲文章を練り直すプラスを増やす

この表のように、校正と校閲が間違いを直す、つまりマイナスを減らすのに対して、推敲はプラスを増やす作業になります。

校正、校閲は、一般的には推敲の後に行われるようです。これは、先に校正、校閲をしたとしても、推敲によって文章が変わった場合に再度校正、校閲の作業が発生するためだと思います。

推敲で文字や情報の間違いを直すことももちろんできますが、それよりも推敲ではプラスを増やすことに集中すべきだといえます。

なぜ推敲が必要か

推敲は、より読みやすい、分かりやすい開発ドキュメントにするために必要な作業になります。

文章を書いているときは、書いている部分に集中すると思います。つまり、なかなか全体を俯瞰することができません。

例えば、あるところは詳しく書いているけど、あるところは説明が足りない、といった問題がありします。このときは、構成を変えたり、文章ではなく表や図で説明した方がよいかもしれません。

このように、推敲をしないと見えてこない改善案があります。よりよい開発ドキュメントにするためにも、推敲が必要になります。

推敲のやり方

それでは、推敲のやり方について見ていきます。ただ、推敲といってもいろんな方法があるようです。

いろいろ試してみて、自分の中では次のやり方が効果的でした。

  1. しばらく寝かせる
  2. 読者になりきる
  3. 音読する

ひとつずつ説明します。

1. しばらく寝かせる

文章を書き終えたら、いきなり推敲を始めるのではなく、しばらく寝かせます。これは、自分とは別の視点で、客観的に文章を読むために必要なプロセスになります。

可能であれば一晩、急いでいるときでも一時間くらいは、推敲までに時間を空けたいところです。

2. 読者になりきる

文章は、もちろん読者が読みます。文章が想定している読者については、文章を書く前の企画段階で決めていると思います。この読者になりきります。

企画について詳しくは、「開発ドキュメントを書く前に決めるべき3つのこと【企画編】」をご覧ください。

3. 音読する

文章をしばらく寝かせて、読者になりきったら、次は文章を音読します。つまり、声に出して読みます。

音読をすることで、目で読むときより「読みやすさ」が分かります。例えば、スラスラと読めなかったり、読んでいて理解できないことがあったりします。

音読をする上で改善点が見つかったら、補足したり、構成を変えたりします。

推敲力を上げる練習

推敲に限らないですが、どんなスキルでも、繰り返し行うことで身についていくと思います。

この推敲力を上げるための練習について、技術ブログを書くことがよいと考えています。推敲に限らず、テクニカルライティング全般について学べます。

技術ブログについて詳しくは、「技術ブログ入門」をご覧ください。

おわりに

推敲をすることで、読みやすさ、分かりやすさが大きく向上します。文章を書いたら、必ず推敲をしたいところです。

あなたがやっている推敲のやり方があれば、ぜひ@zenizhまでご連絡ください。

著者
Hiroki Zenigami

テクニカルライター。開発者向けのドキュメントを書いています。元エンジニア。共著で「現場で使えるRuby on Rails 5」を書きました。

\ よかったらフォローしてください /
関連記事関連書籍
人気記事
applis
アプリケーション開発について学ぶブログ
お問い合わせ
ご意見・ご質問やお仕事のご依頼などは以下よりお願いいたします
お問い合わせ
© 2020-2022 applis