書き手と読み手を苦痛から解放するために、ドキュメント作成時にやっておくといいこと
📌 このnoteで分かること
- 読みやすいドキュメントが組織にもたらす効果
- ドキュメントのアンチパターン
- 読みやすいドキュメントを書くための具体的方法
こんにちは。壮（@sew_sou19）と申します。
メガベンチャー企業でエンジニアとして働いています。
エンジニアとして働いていると、仕様書にはじまり設計書や調査資料、手順書や議事録、報告書…と数多くのドキュメントを書く機会があります。
加えて、フルリモートで働いていたり、日本語が母国語でない方と一緒に働いたりする際は、適切なテキストコミュニケーションがより重要になってきます。
このnoteを読んでくださっている方の中にも、苦痛を感じながら雑なドキュメントを読んだ経験や、読みやすいドキュメントを書くこと自体に苦痛を感じた経験をお持ちの方は多いと思います。
▼雑なドキュメントを読んだとき
「知りたいことにたどり着かなくて時間を浪費する」
「何が言いたいのか分からなくてイライラする」
「結局どういうこと？？？」
▼ドキュメントを書くとき・書いたあと
「この書き方で伝わるのか不安」
「ドキュメントに書いてあることを質問される」
「伝えたいことがうまく伝わっていない」
僕自身、エンジニアに転職した当初はどう書いたらいいのかが分からず、上記のような壁にぶつかっていました。
そこで、既存の読みやすいドキュメントを分析しながら真似ることや、自分と同じように前提知識が少ない人でも分かるように書くことを意識し続けてきました（未経験からの転職で最初は技術的な貢献が難しかったので、ドキュメント作成を頑張っていた）。
その結果、同僚やリーダー、果ては部長からも評価してもらえるようになりました。
直接やり取りすることがあまりない上司(部長)に「ドキュメントが本当にいい。読みやすいのはもちろん、かゆいところに手が届く感じが実にいい」って言ってもらえて、仕事を褒められたのはもちろん嬉しいけど、それ以上にちゃんと部下のことを見てくれる環境で働けてるのがラッキーだなと改めて感じた。
— 壮 (@sew_sou19) January 20, 2022
リーダーから「君は情報の整理が上手でドキュメントが本当に読みやすい。チーム全体の能力向上に繋げたいからドキュメント書く際のポイント共有してほしい」と言われたので、意識していることを言語化しつつテクニカルライティングの本でインプットしてるけど、学びが多い。ついでにnoteにもまとめてる
— 壮 (@sew_sou19) November 28, 2022
リーダーから「ドキュメント作成のポイントを共有してほしい」言われて、自分が気をつけているポイントを言語化すると同時に関連書籍を読み漁り始めました。気付いたのが、自分が意識しているポイントの多くが「テクニカルライティング」という技術に基づいたものであることです。
そこで、これらのテクニカルドキュメントの知識を踏まえて「読みやすいドキュメントを書くためのポイント」をまとめます。
はじめに
エンジニアが書いたコードが資産であるように、ドキュメントも会社やチームにとっての資産です。つまり、ドキュメントを書くことは、コードを書くことと同様にエンジニアの重要な仕事の一つです。
働き始めた当初は「エンジニアはコードを書くのが仕事だから、読みやすいドキュメントなんて二の次でいい」と思っていました。しかし、苦しんでいたときに読みやすいドキュメントに助けられたこともありましたし、ドキュメントによって生産性が大きく向上したこともあり、そんな考えは間違いだと気付きました。
むしろ、シリコンバレーでは ”Every engineer is also a writer.” （エンジニアは皆、作家でもある）と言われているほど、エンジニアという仕事においては読みやすいドキュメントを書くことが重要です。
この認識を持っていただいた上で、まずは、読みやすいドキュメントがもたらす具体的な効果から書いていきます。
読みやすいドキュメントは生産性を上げる
読みやすいドキュメントは「生産性の向上」に繋がります。
仮に、読みやすいドキュメントのポイントを知らない、もしくは書いたドキュメントが読みにくいと、以下のような好ましくない事態に発展します。
何に際しても時間がかかる
読み手はそもそも読むことに時間がかかる
読み手は知りたい情報がすぐに見つけられない
書き手は迷いながら書くので時間がかかる
内容を理解しきれず、書いてあることを書き手に聞いてしまう
コミュニケーショントラブルの原因になる
書き手・読み手双方に問い合わせコストが発生する
ドキュメント作成のモチベーションが下がる
情報の伝達漏れ・伝達ミスが発生する
書いてあるのに見落としてしまう
伝えたいことと違う意図で伝わってしまう
誤った前提をもとに話が進んでしまう
ドキュメントを書くことの目的はいくつかあると思いますが、その中でもエンジニアがドキュメントを書くことの目的を強調するなら、
情報を整理して共有することで、
ミスを防ぎ、コミュニケーションを円滑にし、不要な時間を削減し、
組織の生産性を高めること
だと思っています。図にすると以下のイメージです。
もっと粒度を細かくして目的を定義するなら「読み手が、ドキュメントを読むだけで、次の行動に移せるようになること」だと思っています。
すなわち、せっかく重要なことを書いたにもかかわらず自分以外の誰にも伝わらず（ましてや将来の自分にすら伝わらず）、読み手が次の行動に移せない、という事態は避けるべきです。
書き手にはそうさせないための義務があります。
読みやすいドキュメントを作成することで得られるメリットは「生産性の向上」と抽象的に書きましたが、具体的に挙げるなら以下です。
自分以外の誰かの助けになる／将来の自分の助けになる
分かりやすい仕様書があれば、わざわざコードを読み解かなくても、仕様を把握できる
欲しい情報をすぐに手に入れられる
複雑な内容でも理解が容易になる
そもそも書こうとしている今の自分の助けになる
読みやすいドキュメントを書こうとする→情報の抜け漏れに気付ける
読みやすいフォーマットに落とし込むことで、書くコストを下げられる
書いたあとの良好な反応を予測でき、モチベーションが高まる
円滑なチームワークに繋がる
共通認識を作ることができ、議論が脱線しにくい
ドキュメントを読めば分かるので、休んだ人や後からジョインした人のキャッチアップが容易になる
問い合わせ等のコミュニケーションコストを減らすことができる
さて、こんなにもメリットがあるなら（ドキュメントを書くこと・読むことに苦労した経験がある方なら）、そろそろ読みやすいドキュメントを書きたくなってきたのではないでしょうか。
読みやすいドキュメントを書くには
本題です。
読みやすいドキュメントは、なんとなく読みやすいわけではなく、しっかりとした理由があります。
以下の内容をひとつずつ噛み砕いていくので、まずはドキュメントについての知識を知った上で、ドキュメント作成時に各テクニックを適用するのがおすすめです。
1. 前提を知る
それだと伝わらない
読み手には色んなタイプがいる
読みやすいドキュメントが持つ要素
2. 書き方を知る
書くまえ
■何のために書くのか？
■誰のために書くのか？
■何を書くのか？
書くとき
■読み手の前提知識を想像する
■読み手視点に立つ
■読み手の心情を想像する
■認知特性を利用した表現を用いる
書いたあと
■推敲する
■レビューを受ける
■一部を変更したら全体を見直す
3. テクニック
構成を練るときに気をつけること
文章を書くときに気をつけること
より良い表現にするために試すこと
1. 前提を知る
ドキュメントを書くに際して、知るべき意識を書き連ねます。
読みやすいように工夫を凝らしているつもりですが、それでも量が多いので、興味のない箇所は読み飛ばしてしまっても問題ありません。
それだと伝わらない
以下の認識を少なからず持っている場合、せっかくドキュメントを書いても読み手に伝わらない可能性があります。
「正しいから（間違っていないから）ヨシ！」
「自分が分かるから（他の人も分かるだろうから）ヨシ！」
「このドキュメントを読む人は前提知識があるはずだからヨシ！」
「正しいから（間違っていないから）ヨシ！」
仮に正しいことが書いてあったとしても、その内容が読み手に伝わらないと意味を為しません。
「正しいことさえ書いておけば義務は果たしていて、あとは読み手がいい感じに読んでくれればいい」「正しいことが書かれているんだから、読み解けなかったり書いたことをもとに行動に移せなかったとしたら、それは読み手の責任だ」
…この気持ちはとても分かります。ドキュメントの構成をしっかり考えて、言葉もしっかり選んで、伝わるように書くのは本当に骨が折れる作業です。
先ほども書きましたが、書き手には、書いた内容を読み手に理解してもらった上で行動に移させる義務があります。その義務を果たすためにも、正しいことを書いた上で、それを読み手に伝えやすくする工夫を凝らしたいところです。
そうでないと、情報共有のためにせっかくドキュメントに書き起こしたにも関わらず、情報が伝わらないどころか、むしろコミュニケーショントラブルの原因になってしまいます。非常にもったいないです。
「自分が分かるから（他の人も分かるだろうから）ヨシ！」
書き手と読み手は異なる人間です。
当たり前ですが、異なる人間なので経験量も違えば持っている知識量も異なります。そのため、書いた自分は当たり前と思っていることでも、読んでいる人にとっては初出のことだった、という事態はよく起こります（むしろ起こらないことの方が少ない）。
読み手にとっては、ドキュメント内で知らない単語や概念が出てくると一気に負荷が高まります。
知らないことを理解しようと思考を巡らしたり、調べたりする
↓
「書き手が伝えたいこと／読み手が知りたいこと」から脱線する
↓
軌道修正する際に「どこまで読んだっけ」「何を調べてたんだっけ」と思い出す・記憶を繋げる作業が発生する
↓
このとき、読み手にかなりの負荷が生じる
読み手にとって知らない単語が出てくると、ドキュメントを読むことに対する集中力が途切れてしまいます。
読み手は、もう一度読み直す必要に駆られ、面倒だからと読むことを後回しにし、しまいには読むこと自体を諦めてしまうかもしれません。
「もったいないドキュメント」の増殖に寄与してしまいます。
「このドキュメントを読む人は前提知識があるはずだからヨシ！」
読み手の前提知識を正しく想像せず、書き手の安易な思い込みをもとに書いてしまうと、読みにくさに繋がります。
「その読み手は果たしてこの知識を知っているだろうか？」という問いは、ドキュメント作成時は常に持っておくべきです。そして、もし迷った場合は前提知識がない前提で書くべきです。
文章中に簡単な説明がある場合、前提知識がある人は「ああ、この説明か」と読み飛ばすことができるので大した負荷にはなりません。前提知識がない人にしてみると、いちいち別のウィンドウや別の端末で該当の単語をググらなくて済むので効率がいいです。
(△)「CSRを用いるので、SEOに関する懸念がある」
(○)「ブラウザ側でHTMLを生成するCSRを用いるので、SEOに関する懸念がある」
もちろん、全ての単語に対して説明を行おうとすると読みにくくなってしまうので、適度にする必要はあります。
「説明書くのが面倒だし、大体これ読む人は分かってるでしょ」と少しばかりの手間を惜しむと、これまた「もったいないドキュメント」の完成です。
ここまで書いてきたように、ドキュメントの書き手には、読み手に伝える義務が発生します（そうでないと書く意味がない）。そして、伝える義務を怠ると途端に伝わらなくなります。
読み手がドキュメントを読んでも理解できない／意図が伝わらない場合、それは100%書き手の責任です。
読み手には色んなタイプがいる
当たり前ですが、読み手は1人ではありません。
多くの人が読み手になり得ます。
読み手によってはドキュメントの位置付けが変わってきますし、必要な情報も変わってきます。そのため、書き手が想定していないような情報を求めていたり、意図しない読み方・受け取り方をすることがあります。
▼例：ログインAPIの仕様書に対して
エンジニアA「ログインAPIってどこで使われるんだろう」
エンジニアB「どういうリクエストを投げればいいのか知りたい」
エンジニアC「問い合わせ対応のために全体像を把握したい」
エンジニアD「ジョインしたてで何も分かってない」
エンジニアE「ステータスコード409ってどういう状況か知りたい」
エンジニアF「にゃーん」
読み手にはいろんなタイプがいるため、
求める情報は、読み手によって異なる
情報の探し方も、読み手によって違う
どんな読み手にも内容は一意に伝わる必要がある
内容は一部しか読まれない（全部を読んでもらえるとは思わない）
という前提を把握しておくと、読み手に甘えることが危険であると理解できます。読み手に甘えてしまうと、一部の人（往々にして自分だけ）にしか伝わらなくなります。
読みやすいドキュメントが持つ要素
「読みやすさ」とは、読み手がドキュメントに対して抱く感情や体験です。ユーザビリティの要素を孕むため、この観点からアプローチします。
先に結論を書くと、読みにくいドキュメントには得てして「効率性」と「快適性」が欠如しています。読みやすいドキュメントは「効率性」と「快適性」を持ちます。
まずはユーザビリティの要素を軽く説明します。
ユーザビリティに関しては、国内規格（JIS Z 8521:2020）や国際規格（ISO 9241-11:2018）がありますが、小難しいので詳細は以下に任せます。
「ユーザビリティ」を個人的解釈で意訳すると「ある目的を達成するために用いた際の、有効性・効率性・快適性」だと思っています。
つまり、要素はざっくり3つあります。
- Effectiveness（有効性）
- Efficiency（効率性）
- Satisfaction（快適性）
これを「読みやすいドキュメント」の要素と照らした場合、重要なのは「効率性」と「快適性」だと思っています（有効性のないドキュメントはあまり書かれないはず）。
■効率性
「短時間で知りたい情報を知ることができるか」という要素です。
具体的には
見出しが整っていて欲しい情報をすぐ見つけられる
どこに何が書いてあるか分かりやすい
理解しやすいので速く読み進められる
などです。
逆に言えば、道筋が立っておらず欲しい情報にたどり着くまでに時間がかかったり、不要なことが多く書かれていて読むこと自体に時間がかかってしまうドキュメントは、効率性が欠けています。
これだと読み手の体験（ユーザビリティ）を損なって「読みやすいドキュメント」からは遠のいてしまいます。
■快適性
「読んでいてストレスを感じないか」という要素です。
具体的には
一文一義など簡潔な表現をする
肯定的な表現をする（ネガティブ・否定的な表現をしない）
差別的な表現を用いない
などです。
否定的・差別的な表現によって読み手に余計な不快感を抱かせてしまったり、周りくどい書き方によって読む労力を増やしてしまうドキュメントには、快適性が欠けています。
読み手は、読んだあとに「大変だった…」という徒労感に襲われて「こんなドキュメントもう読みたくない」と悪い印象を抱いてしまうでしょう。
2. 書き方を知る
読みやすいドキュメントの前提（概念）を把握したので、次は具体的な方法論です。
書くまえ
まず知るべきは「ドキュメントを書く前」に行うことです。
読みやすいドキュメントの大半の要素は、ドキュメントを書き始める前に決まると思っています。「何のために・誰のために・何を書くのか、を明確に定めること」が、読みやすいドキュメントを作成する上で重要です。
プログラミングで言えば、いきなりコードを書き始めるのではなく、最初にしっかりと設計をしておくイメージです。それによって綺麗（DRY、Readable）なコードが書けるように、ドキュメントを書く前にポイントを押さえて設計することで、読みやすいドキュメントが書けるようになります。
■どう設計するか
以下の3ステップです。
①何のために書くのか？：ドキュメントの目的を定義する
②誰のために書くのか？：読み手を定義する
③何を書くのか？：情報を整理する
一つずつ深掘っていきます。
①何のために書くのか？：ドキュメントの目的を定義する
「何のために、何を伝えるドキュメントなのか」を明確に定義します。いきなり書き始めるのではなく、ほんの数十秒でもいいので考えてみてください。
目的が定まっていないドキュメントは「ドキュメント」でない（メモと同義）
目的を一言で定義できるのが理想
定めた目的をドキュメントの「概要」として書く
一つのドキュメントに対して目的は一つに絞ります。目的が複数あるドキュメントは読み手に高い負荷をかけてしまいます（これって結局何について書かれたドキュメントなんだっけ？と余計な思考をさせてしまう）。
主目的が複数存在する場合はドキュメントを分けるべき
主目的に関連する副目的ならOK
（×）このドキュメントは、案件の概要と機能の仕様をまとめつつ、進行の方法について書くことが目的だ
（○）このドキュメントは、機能の仕様を、後からジョインしてくる人も理解できるように整理するのが目的だ
②誰のために書くのか？：読み手を定義する
「誰に伝えるためのドキュメントなのか」を定義します。誰を読み手と想定するかで書き方が変わってくるためです。
読み手が定まっていないドキュメントは「ドキュメント」でない（メモと同義）
読み手が定まっていないと、主語や記述対象の揺れに繋がる
読み手が定まっていないと、読む人の前提知識に依存した内容になる
読み手を定義したら、読み手の前提知識を想像します。この段階で前提知識の想像を行うことで抜け漏れのない設計が行えます。
定義した読み手が理解できる内容にする
想像した前提知識以外のことは必ず説明する
複数の読み手を定義した場合、最も前提知識がない読み手を対象とする
③何を書くのか？：情報を整理する
書く内容の設計です。ここの肝は情報の整理です。
ドキュメントの目的を満たせるように、情報を整理する
伝えたいことを構造化（ロジックツリーや箇条書き等）する
頭の中でも紙に書いてもOK
ざっくりの構造とドキュメントの見出しがリンクすることを意識する
定義した読み手が理解できるように、情報を整理する
全体から部分への展開
概要から詳細への展開
既知から未知への展開
具体的な情報の整理方法・構成の練り方はテクニックのセクションで紹介します。ここでは「定義した読み手に対して、どういう情報があれば定義した目的を達成できるかを考え、洗い出す作業が必要」と思っていただければ十分です。
書くとき
読み手に配慮する、これに尽きます。
書く前の設計をうまくやったとしても、どのように伝えるかによって、読み手の理解度に大きく影響します。
読み手の理解度を上げるためのポイントを書いていきます。大きく4つです。
①読み手の前提知識を想像する
②読み手視点に立つ
③読み手の心情を想像する
④認知特性を利用した表現を用いる
①読み手の前提知識を想像する
書く前にも想像したと思いますが、書くときはより具体的に想像していきます。
読み手は書き手ではない
書き手が当たり前と思っていることは、読み手にとっては当たり前ではないことが多い
読み手とする具体的な人を設定するとイメージしやすい
「Aさんならこの説明が必要そうだな」
読み手に期待しすぎない
読解能力が高くて行間を読んでくれる人とは期待しない
全く前提知識のない第三者でも容易に理解できるように書く
一意に受け取ることができる表現を用いる
ドキュメントは、コミュニケーションの流れの中で作成されることもありますが、そのような場合はコンテキスト（文脈）や行間が重要になります。
まさにやりとりをしている今は、書き手も読み手もコンテキストや行間を把握するのに苦労しませんが、それは情報がホットな今だけです。
1週間後、1ヶ月後、1年後…と時間が経てば経つほど、書き手も読み手も行間を読み取れなくなり、行間に依存したドキュメントの価値は下がっていきます。
②読み手視点に立つ
「自分がもし読み手だったらどう思うか？」という視点を忘れずに書く必要があります。
読み手を置き去りにしない
書き手が書きたいことを書くのではなく、読み手が読みたいこと（＝知りたいこと）を書く
読み手が期待していることを想像する
読み手が知らないことを前提に話を進めない
読み手が知っていることから順を追って説明する
読み手は、階段を一段ずつ上がっていくように説明されると理解しやすい
反対に、知らないことが一段目にあるとつまづいて理解が難しくなる
読み手が階段の一段目を登れるかに配慮する
③読み手の心情を想像する
読み手の視点に似ていますが「読み手はこのドキュメントに触れているとき、どのような感情を抱くのか」を想像することです。そうすることで、より読みやすいドキュメントに進化させることができます。
目的と読み手に応じた表現を用いる
そのドキュメントがどんな時に読まれるのか想像
その時の読み手の心情（ポジティブなのかネガティブなのか）を想像
それに即した表現にする
不安・不快にさせない
不安要素を取り除く
差別的な表現はしない
否定的な表現を多用しない
余計な疑問を抱かせない＝読んでいてストレスを与えない
主語を揃える / 省略しない
前提を説明する
不要なことは書かない
④認知特性を利用した表現を用いる
人間の特性を利用するためのロジックが存在します。
ただ、このロジックを知らなくても読みやすいドキュメントは書けるので、興味のない方は飛ばしてしまって問題ありません。
「認知特性」とは、人間の認知心理学に基づいたロジックのことです。噛み砕けば「どのようなドキュメントだと人間は受け入れやすいか」を論理立てる根拠です。
「認知特性」を利用すると、読み手が感覚的に読みやすい・理解しやすい表現ができるようになります。ここでは、認知特性自体の説明は省略し、認知特性に基づいた読みやすい・理解しやすい表現の例を挙げていきます。
「認知特性」を利用した表現
▼ぱっと見の印象をよくする：好印象形成の支援
感情的に好まれる見た目にする
- 情報量を少なく見せる
- 好まれる色使い（色を多用しない）
感情的に好まれる構成にする
- 全体と部分の関係を分かりやすくする
- どこに何が書いてあるのか分かりやすくする
▼意味のまとまりを意識的に作る：チャンキングの支援
短期記憶の特性：20秒しか持たない
- 内容のまとまりごとに見出しをつけて認知しやすくする
短期記憶の特性：一度に持てるのは7個まで
- まとまりは7個以内にする
- 箇条書き、項目数、フロー図や構成図の要素も同様
▼既知の知識と関連させる形で情報を提供する：検索支援
長期記憶の特性：既有知識は理解しやすい
- 具体例や比喩を用いる
- なじみのある世界に引きつけた表現にする
抽象度ばらばらに書いてきましたが、具体的かつ細かなポイントはテクニックのセクションに任せます。ひとまずは次に進みましょう。
書いたあと
読み手に配慮しながら書くだけでも十分かもしれませんが、もったいない部分が残ります。書くときに配慮した上で、もう一手間加えることで飛躍的に読みやすいドキュメントに成長します。
ポイントは3つです。
①推敲する
②レビューを受ける
③一部を変更したら全体を見直す
①推敲する
まずは推敲です。
自身で書いた文章を読み直すことで、客観的に気付くことが多く、ドキュメントを読みやすくできます。
一般的な人間の能力は、書く力より読む力の方が優れていると言われています。
書くときには違和感がなかったとしても、読み直す際には「なぜこんな駄文を！？」と思った経験をお持ちの方も多いと思います。
そのくらい能力差があるので自身で推敲するだけで効果は高いのですが、意外とやっていない人が多いです。
読み直しの視点
体裁の確認
内容の一貫性の確認
ドキュメントの目的とずれていないか
伝わりやすい書き方になっているか
最後に通読
推敲のポイント
漏れダブり
文と文とのつながり
接続詞（用いる接続詞によって意味が異なる。伝わりやすい表現か？）
②レビューを受ける
プログラミングと同じように、ドキュメントもレビューを受けることで客観的なフィードバックを得ることができ、質の向上に繋がります。
「ドキュメントのレビューなんて…」とネガティブな印象を抱く方もいらっしゃるかもしれませんが、本質はプログラミングと同じです。レビューされる側はもちろん、レビューする側も気付きを得られるのでおトクです。
さらに、ドキュメントのレビューを行うことで組織自体にドキュメントに対する意識を高めることができ、結果的に読みやすいドキュメントを書く文化を根付かせることもできるので、一石三鳥になったりします。
レビュイーが得られること
伝わっていること・いないことを把握できる
想像した読み手の前提知識と、実際との差分を把握できる
読みやすさのポイントに確信を持てる
レビュワーが得られること
いい書き方と悪い書き方を客観的に知ることができる
指摘したポイントを自身のドキュメントにも反映できる
読んだドキュメント分の知識が増える
組織が得られること
ドキュメントに残す文化が根付く
読みやすいドキュメントが増殖する
コミュニケーションが円滑になり生産性が向上する
レビュー観点については、最初のうちは以下あたりを参考にしていただくと良さそうです。やっていくうちに、足したり減らしたりして最適なリストにしていただけると嬉しいです。
- タイトルから文章の目的が分かる
- 全体の構成がロジカルに組み立てられている
- 見出しから内容が分かる
- 文と文とのつながりがある
- 必要な情報の抜け漏れがない
- 不要な情報が書かれていない
- 1文が長すぎない
- 表記の揺れがない
- 固有名詞の誤りがない
- 誤字脱字がない
自身でも推敲する際に、チェックリストとして活用してみてください。
③一部を変更したら全体を見直す
自身で推敲したり、レビューを受けたりして一部を変更することがあると思います。その場合、変更した箇所だけではなく全体を見直すことで、より読みやすいドキュメントにすることができます。
というのも、一部分を変更しただけでも全体の整合性が崩れることがよくあるからです。
全体の整合性を再度確認する
筋道が立っているか確認する
部分を変更すると、全体に影響がある
再度全体を確認することで、よりよい構成にできることが多い
面倒ではありますが、変更する→全体を見直す→整合性が取れない部分を修正する→全体を見直す、という作業を繰り返すことでより読みやすいドキュメントになります。
最初は時間がかかるかもしれませんが、慣れれば短時間で行えるようになります。ものは慣れです。
重要なのは、書き直すことを厭わないことです。「せっかく書いたのにここを変えるとあそこも変えないといけない…」と躊躇してそのままにしておくと、どんどん読みにくいドキュメントになっていきます。
今、少しの手間をとることで、将来読み手にとっては大きなメリットとなって返ってきます。手間を被るのは書き手ひとりですが、将来まで含めると読み手はかなり多くの人数になるため、コスパがいいです。
3. テクニック
ここまでは概念寄りで、やや抽象的な話をしてきました。ここからはより具体的で、今すぐご自身のドキュメントに反映できるテクニックを書いていきます。
ここから先は
¥ 500
自身のキャリアで得た知見について言語化しています。執筆活動の励みになります！