こんにちは。
SREホールディングス株式会社のエンジニアの高柳です。
エンジニアと言いつつもドキュメントを書くことって多いですよね。
設計書や仕様書はもとより、提案書や報告書なんかのドキュメンテーション業務もざらにあるかと思います。
今回は、「ドキュメント作ってもめっちゃ不毛な添削ばかり😢」「ドキュメント書くの苦手なんだよなぁ」といった方に向けて…
それ、テクニカルライティングでちょっとだけ改善されるかもしれません。
テクニカルライティング？
テクニカルライティングとは、技術的な内容を目的や読み手に合わせて分かりやすく伝える手法です。
製品の取扱説明書や論文、ホワイトペーパーなどの技術文書を書く専門の "テクニカルライター" という職業もあるようです。
しかし、かの Google 様曰く、以下のようなお言葉がございます。
確かにエンジニアでも API のリファレンスから技術的な説明まで、わかりやすく伝える必要があるシーンは多いです。無用な質疑の時間が減れば作業の効率化にもつながるかもしれませんね。
とはいえ、テクニカルライティングはこうしろ！といった明確な方法は無いように感じます。
(当社が提唱するーーとかはある)
今回は、だいたいみんな言ってるテクニカルライティングの基本っぽいものを高柳なりにまとめたものをご紹介します。
テクニカルライティングの流れ
- 作成するドキュメントの目的と読み手を明確にする
- 書くべき情報を収集して整理する
- わかりやすく、簡潔な文章で書く
作成するドキュメントの目的と読み手を明確にする
まずはそのドキュメントは「誰が」見て「どういうこと」が伝わればよいか？を考えます。
例えば議事録の目的は「関係者」に「決定したことを共有する」ことですし、障害報告書であれば、「顧客」へ「お詫びと原因・対策の報告」になります。
そのドキュメントを見た人がどういう行動を取ればいいか、どういう状態になって欲しいかも明確にしておきましょう。
書くべき情報を収集して整理する
まずは伝えたいことを頭の中から発散させて、書くべき情報を集めましょう。
集めたバラバラの情報を頭の中でまとめていきなり書き始めるのではなく、階層のあるツリーの形に整理して書き出してみます。
自分は Markdown などで階層構造を作って整理することが多いです。
これをやらないと次のような状態になりがちです。
①説明の順番がおかしくなる
②何度も繰り返して説明し、ダブりが生じる
③必要な情報が抜ける
④書き上げるまでに時間がかかる
⑤筋道が通っていないため、読み手が理解しにくくなる
構成している要素を「大きなテーマから具体的な内容」に分解していきましょう。
段階を追って知識を付け加えることがわかりやすさに繋がります。
各情報にキーメッセージを付けてみて繋げ、ドキュメントのストーリーを確認していくとなお良しかなと思います。
わかりやすく、簡潔な文章で書く
ここからはドキュメントの書き方のお話になってきます。
- 一文一義で書く
1つの文には、1つの主題に絞って書きましょう。
複数の内容が盛り込まれた文章は理解しにくくなります。
- 重要なことから書く
最も重要な内容や目的を最初に書きましょう。
せっかちな人は途中までしか読まないかもしれません。
- 能動態と受動態を使い分ける
使用方法などを書く時に、読者(ユーザー)の視点の操作は能動態で書きます。
逆にシステムの動作は受動態になるように書きましょう。
- できるだけ具体的に書く
具体性がない表現は、書き手の意図通りに伝わりません。
報告などのドキュメントは5W1Hを意識して盛り込みましょう。
- 肯定形で書く
否定表現は読み手が理解しづらいだけではなく、ネガティブな印象を与えます。
- 列挙には箇条書きを使う
項目を並べるときは箇条書きを活用すると、並列関係が視覚的にわかりやすくなります。
まだまだ色々とありますが、長くなってしまうのでこのあたりまでにします。
おわりに
Googleの資料にある通り、作ったドキュメントは少し寝かせてもう一回読んでみることもおすすめです。
夜中に書いたソースコードも朝見ると荒ぶっているなと思うこと、ありますもんね。
ドキュメントの書き方を書いておきながら、文章がおかしかったりして。
なにかご指摘があればコメントをお願いします。
この記事ですこしでも「へーっ」って思っていただけたら幸いです。
参考
以下のブログや書籍について参考にさせていただきました。
ご興味あれば是非見てみてください。
Discussion