2. 推敲

ドキュメントの初稿が書けたところを想像してください。どうすれば原稿をより良くできるでしょうか？ ほとんどの場合、公開される最終的なドキュメントへ向かう作業は反復的に行われます。真っ白なページから初稿を作るのが最も手間がかかる部分ですが、その後にも文書を手直しする時間を十分に確保しておくことを忘れないでください。

この章で紹介する推敲のテクニックを使えば、あなたの原稿は読者が必要とする情報をより明確に伝えられるようになります。いずれかのテクニックを一つ使うか、全て使うかは自由です。あなたに合ったやり方を見つけ、それを執筆ルーチンの一部とすることが重要です。

この章で示す推敲のテクニックは『テクニカルライティング One』で説明した執筆・推敲スキルを元にしており、一部は『テクニカルライティング One』で示した便利なテクニックのまとめとなっています。きちんと復習したい場合は テクニカルライティング One を見てください。

スタイルガイドを採用する

企業・機関・大規模なオープンソースプロジェクトはよく既存の (または独自の) スタイルガイドを利用してドキュメントを執筆します。例えば Google Developersにあるドキュメントプロジェクトの多くは Google Developer Documentation Style Guide を採用しています。もしあなたがスタイルガイドを使ったことがないなら、Google Developer Documentation Style Guide を見て少し圧倒されるかもしれません。コンピューターのインターフェースのドキュメント・フォーマット・文法・約物といったトピックに関する詳細な手引きが示されているからです。スタイルガイドの短縮版 (highlights) を採用するところから始めるのもよいでしょう。

チームドキュメントや小規模なオープンソースプロジェクトのドキュメントでは、短縮版で十分な場合もあります。

Google Developer Documentation Style Guide の短縮版にあるガイドラインのうちいくつかは『テクニカルライティング One』でも触れています。例えば次のテクニックには聞き覚えがあるでしょう:

スタイルガイドの短縮版には他にもテクニカルライティングで利用できるテクニックが多く載っています。例えば:

読者のように考える

あなたの読者は誰ですか？ 一歩引いて、読者の目線から原稿を読んでみてください。ドキュメントの目的が明確なこと、そして読者が知らない可能性のある全ての用語や概念の定義があることを確認してください。

読者のペルソナ (どんな人物であるか) を説明しておくと役立つ場合もあります。ペルソナを構成する属性の例を示します:

その上でペルソナを意識しながら原稿を読み直してみましょう。あなたが仮定したことを読者に伝えるのは特に重要です。また何らかのトピックの復習が必要な読者のために学習リソースへのリンクを提供することもできます。

少数のペルソナに過度に依存すると、対象が狭すぎて読者の大部分にとって役に立たないドキュメントとなってしまいます。

このトピックに関する復習やさらなる情報については、『テクニカルライティング One』の自習用教材の 9. 対象読者の章を参照してください。

声に出して読む

文書が置かれる環境に応じて、文章のスタイルは読者を疎外することもあれば惹き付けることもあり、中には読者を退屈させるスタイルも存在します。望まれる文書のスタイルは読者にある程度依存します。例えば、ボランティアを集めることを目的とした新しいオープンソースプロジェクトのコントリビューターガイドであれば、普通よりもくだけた会話調のスタイルを採用するかもしれません。また商用エンタープライズアプリケーションの開発ガイドは堅いスタイルを採用することでしょう。

執筆した文章が会話調であるかを確認するには、声に出して文章を読んでください。歯切れの悪いフレーズや長すぎる文、その他の不自然に感じる部分に耳を澄ませましょう。自分で読む以外にも、他の人に頼んで原稿を声に出して読んでもらうこともできます。

読者に合わせた文章のスタイルの調整についてさらに詳しくは、Style and authorial tone を参照してください。

時間を空けて読む

初稿 (または第二稿か第三稿) を書き終えたら、しばらく放っておきましょう。数時間後に頭の中をスッキリさせてからもう一度読んでください。まず間違いなく改善すべき点が見つかることでしょう。

環境を変える

原稿を紙に印刷し、赤ペンを片手にレビューするというやり方を好むライターもいます。環境を変えて自分の原稿をレビューすれば改善点が見つかりやすくなるかもしれません。この古典的なテクニックを現代的に行いたいなら、ドキュメントを別のファイルにコピーし、フォント・サイズ・色を変えるとよいでしょう。

ピア編集者を見つける

エンジニアがコードのレビューでピア (仲間) を必要とするように、ライターには原稿に対するフィードバックを提供する編集者が必要です。あなたの原稿をレビューして的確で建設的なコメントを付けてくれないかと誰かに頼んでみましょう。ピア編集者はドキュメントが扱うトピックの専門家である必要はありませんが、あなたが採用したスタイルガイドを知っている必要があります。

練習問題

取り組んでいる文書があるなら、この章で紹介したテクニックを使ってそれを改善してください。もし作業中の文書がないなら、次の段落を推敲してください:

Determine whether or not you can simplify your document through the use of terminology that is equivalent but relatively shorter in length and therefore more easily comprehensible by your audience. It's important to make sure your document is edited before it is seen by your audience, which might include people that are less or more familiar with the matter covered by your document. The first thing you need is a rough draft. Some things that can help make your document easier to read are making sure you have links to background information, and also checking for active voice instead of passive voice. If you have long sentences you can consider shortening them or implementing the use of a list to make the information easier to scan.

(ドキュメントを長さが比較的短い等価な単語の利用によって、読者によってより簡単に理解されるように単純化できないかを考えてください。あなたのドキュメントがカバーする事項についてあなたよりも詳しかったり詳しくなかったりする読者があなたの文書を目にする前に、それが推敲されていることを確認するのは重要です。最初に必要なのは草稿です。ドキュメントをより読みやすくするのに役立ついくつかのことは、予備知識へのリンクを確認すること、受動態ではなく能動態が使われていることを確認することです。もし長い文があるなら、短くするかリストにするかして情報を取り出しやすくしてください。)

読者があなたの文書を理解できるように、次の基本的な推敲の原則を適用してください:

  • 受動態ではなく能動態を使う。
  • 同じ意味を持つより簡単な単語を使えないかを考える。
  • 予備知識へのリンクを示す。
  • 長い文を短い文もしくはリストに分ける。
広告
このページの文章はテキストゆれないくんを使って校正されました。