レッスン1: 明確に書くための最初のステップ
ソフトウェアエンジニアの皆さん、技術文書(いわゆるテクニカルライティング)を書くことを考えるだけで叫びたくなるなら、このシリーズはまさにあなたのためのものです。執筆プロセスを小さな記事に分解することで、気が重い作業というよりも、挑戦しがいのある面白い課題のように感じられるようにします。
念のためお伝えしておくと、あなたはゼロから始めるわけではありません。優れたテクニカルライターになるために必要なスキルの多くを、あなたはすでに持っています。あなたは論理を操り、コードでエレガントな解決策を組み立てるプロフェッショナルです。正確であること、複雑な問題を分解すること、複雑なシステムを説明することにも慣れています。それこそが、まさに優れたテクニカルライティングの本質なのです。セミコロンの代わりに言葉を使うだけです!
最初のミッション: 明確さを大切にする
明確さは、優れたテクニカルライティングの土台です。あなたの目標はこうです。ドキュメントを読む人が誰であれ、混乱することなく、あなたが何について話しているのかを正確に理解できるようにすること。チームメイトであれ、プロジェクトに新しく参加した開発者であれ、エンドユーザーであれ、その相手が理解できるドキュメントにすることに集中しましょう。
技術文書をより明確にするために、意識すべき5つのシンプルなポイントを紹介します。
1. 読者を理解する(それが未来の自分であっても!): 誰のために書いているのでしょうか?読者の技術的理解のレベルはどのくらいでしょうか?言葉を選び、概念を説明する際には、そのことを意識してください。一つのコツとして、エンドユーザー向けの技術文書の多くは、読者の学年レベルを8〜10年生程度と想定しています。つまり、平均的な中学2年生程度でも内容を理解できるということです。非常に専門性の高い内容であれば、学年レベルは10〜12年生程度と少し高くなることもあります。Hemingwayのような読みやすさチェッカーを使って、学年レベルを確認してみましょう。
2. KISS(シンプルかつ分かりやすく!): 専門用語や過度に複雑な文を避けましょう。頭は良いけれど、ドキュメントを何度も読み返す時間はないかもしれない相手に説明していると想像してください。特に読者がエンドユーザーで、あなたの業界や技術に詳しくない場合は、なおさら重要です。
3. 1つの文に1つのアイデア: 短く焦点の絞られた文の方が理解しやすくなります。複雑な情報を、より小さく扱いやすい単位に分解しましょう。目安としては、文がページ(MS WordやGoogle Docs上)で1.5行を超えるようであれば、2つの文に分けて書き直すとよいでしょう。
4. 構造はあなたの味方です: 見出し、小見出し、箇条書き、番号付きリストを使って情報を論理的に整理しましょう。これにより、読者は必要な情報を見つけやすくなります。1つの大きな文章の塊にして読者に多くの認知的労力を強いるのではなく、情報をより小さく読みやすい単位に分割するとイメージしてください。
5. 能動態を使う: 能動態を使うと、文章がより直接的で追いやすくなります。「そのプログラムは実装された」ではなく、「私たちはそのプログラムを実装した」のように書きましょう。
以上が最初のステップです!誰でも実践できるシンプルなアイデアばかりです。まずは、説明をできるだけ明確でシンプルにすることに集中してみましょう。今週のドキュメント作成のタスクでぜひ試してみてください。
このシリーズを読み続ければ、自分のすばらしい成果を文書化することが、決して怖いものではないと分かるはずです。それどころか、やりがいのあることにもなり得ます!次回は、テクニカルライティングのもう一つの重要な側面である「ドキュメントをコミュニケーションの手段として捉えること」について掘り下げます。