はじめに
こんにちは。さとたいです。
この記事では、ドキュメント作成って難しいな～て思いと、そう感じる原因と自分なりの対策を考えて書いていこうと思います。
この記事を作成し終えるころには少しでも苦手意識がなくなり、ドキュメント作成に対して前向きになれたらいいなと思います。
ドキュメント作成って難しい
私は最近、とあるサービスのナレッジなどを後続の人に引き継ぐためドキュメントを作成しているのですが、全然うまく書けません。
項目分けをそれなりにしてみたり、表を使って見やすくまとめているつもりなのですが、いざレビューしてもらうと「～の情報が不足している」とか「～はどういう意味ですか？」など問題点が多く挙がります。
情報の過不足だったり、そもそも内容が伝わっていないことが多く、指摘されるたびにどんどん自信がなくなっていきます...
こういった状況を打開したい気持ちはありつつ、何を意識したり変えていけばいいのかわからない状態です。
どこを難しいと感じる？
なぜドキュメント作成が難しいと感じるか考えたときに3つほど浮かびました。
- 作成する目的をしっかり理解していない
- 簡潔・抽象的にまとめられない
- なんとなくで構造化している
１個ずつ見ていこうと思います。
1. 作成する目的をしっかり理解していない
何のために作成するか考えてからドキュメントを書き出すようにしているのですが、ここが甘いのかもしれません。
「～を伝えるために書くぞ！」と目的を整理しても、書いていくうちに「結局何の情報が必要なんだっけ...？」となり迷子になることがよくあります。
この記事を書きながら、私は目的を抽象的にとらえすぎるせいで、具体的にどんな情報が必要かわからなくなっているように感じました。
もう少し具体化して考えられれば、必要な情報も見えてくるのかもしれません。
2. 簡潔・抽象的にまとめられない
目的を見失い、何を書いていいか迷子になると、次はとりあえず「必要そうな情報をひとしきり書いていく」という行動になりがちな気がします。
必要な情報を探すためにひとしきり書いた結果、余計に散らかってしまい結果的に具体的な情報ばかりの冗長なドキュメントが出来上がります。
全部書き出してから整理するのは、私には合っていないやり方なのかもしれません...
3. なんとなくで目次を作成している
目的を整理した後、まず目次と小見出しを作成して完成イメージを考えるのですが、適切に小見出しを切り分けられていない気がします。
起承転結というか、どのような順番で書けば相手に伝わりやすいか想像が足りないのかもしれません。
そもそも、目的をしっかり整理できていなければ小見出しを適切に分けられるはずもなく...。
どんな対策ができる？
上で挙げたことに対してどのような対策ができるかも考えてみます。
1. ドキュメントの目的をしっかり理解する
難しいと感じることを整理していて、「ドキュメントの目的をしっかり理解すること」がいま最も必要な対策に感じてきました。
目的がはっきりしていれば必要な情報もおのずと整理できますよね。
自分の中で「目的まとまった！」と思っても、形だけでも疑ってみたり、
- Why（なぜ）
- Who（誰に）
- What（何を伝えたい）
を意識して、抜けているものがないか考えてみたり、
自分の中で必要なピースを決めて考えてみるのも良いかもしれません。
当たり前ですが、分からないことが出たときはすぐ誰かに聞くようにもしましょう。
2. 必要な情報を整理する
目的がしっかり理解できていれば、目的に紐づく情報も整理しやすくなります。
しかし、何でもかんでも書くと散らかるので使うものをいくつかに絞れるといいと思います。
書き出してからも必要最低限の情報を意識し、削れそうなものはどんどん消していき簡潔にまとめるようにしましょう。
そこで必要なものが抽象化で、具体的すぎる見出しや文章、データも抽象化することで量をだいぶ減らせます。この部分は慣れや経験によるところが多いと思うので、機会を逃さず何度も失敗するのがいいと思いました。
3. 読み手がスムーズに読めるようにする
必要な情報を整理するとも被りますが、読み手が欲している情報を見極め、最低限のものだけ書くことも大切です。
「読み手は何も知らない・わからない」という意識をもって書き進め、そのなかでも具体と抽象のいい塩梅を見つけることで、スムーズに読めてかつ理解しやすいドキュメント作成が実現できると思います。
理想すぎてすぐ実践できる気はしませんが...意識することが大事だと思います
最後に
初めてQiitaの記事を書きましたが、マークダウン初心者すぎてのっぺりした出来上がりになりました...笑
ネガティブな感情が出まくった記事ではありますが、自分なりに現状を整理し、対策を考えるところまで行けてよかったと思います。
モヤモヤしながら作業したり、いろいろ指摘されるとへこむことも多いですが前向きに、Try & Errorを積み重ねていけたらいいなと思いました！