【エンジニアの悩み】ドキュメント作りの3つのヒント

HSP

エンジニアの業務の中には、ドキュメントの作成することがよくあります。

でも、ドキュメントを作るのはプログラミングのように具体的なやり方がなくて、悩むエンジニアも多いです。

そこで今回は、ドキュメント作りの3つのヒント、を解説していきます。

ぜひ、参考にしてみてください。

【大前提】ドキュメントは読まれるためにある

大前提として、ドキュメントを作成するということは、それを読む人がいる、ということを想定して書かれていないといけません。

ドキュメントは、誰かが読み、その人が納得してはじめてその意味があります。

つまり、なにより大事なのは相手が納得することです

ここからは、相手が納得してくれるドキュメントの作り方のコツを3つ、解説していきます

コツ1: 課題を解決する

ドキュメントには相手が抱える課題を解決するアイデアが書かれていることが前提です。

なので、ドキュメントには現状と理想を示し、そこに解決策を提示されている必要があります

ここでおすすめな方法が以下の3点を盛り込むように書くことです。
  • ASIS = 現状の問題点
  • TOBE = どうあるべきかの理想
  • TODO = 解決するために具体的に何をすべきか

例えば、エンジニアの開発現場で指示書を作成を仮定して、内容は「ページ速度をより速く表示されるように改善する」ということにしましょう。

すると、指示書の内容はこんなふうになります。
ASIS:
    - ページ速度が遅く、ユーザがサイトを閲覧するときにストレスになっている
    - ページの離脱率につながっている
    - ページ速度に問題がある

TOBE:
    - ページ速度を向上させる
    - 2倍程度のページ速度を目標とする

TODO:
    - 画像を圧縮し、ページにおける画像のロード時間を短縮する
    - サーバにキャッシュし、ロード時間を短縮する


ここでは、テキストで示しましたが、ドキュメントの形式がエクセルでも、ワードでもこのように情報が整理されていればOKです。

こういうドキュメントであれば少なくとも、この指示書を渡された人は

なにをすればいいの?

と悩むことはありません。

 

 

コツ2: 結論から書く

そもそも、ドキュメント作成する以上は読まれないと意味がありません。

では、読みたくなるドキュメントってどんなものでしょうか。

れは、相手が知りたいことを知りたい順に書かれているドキュメントです。

そして、それを実現する一番簡単な方法が、結論から書くことです。

先の例でいうと、このような書き方をされても読み進めたいとは思いません。
- サーバの設定を修正するために、設定ファイルをこのように書き換えます
- こうすることでキャッシュを有効にすることができます

コツ1: 課題を解決する、で紹介したような書き方をしましょう。

コツ3: 粒度を揃える

情報の粒度が揃っているとドキュメントはグッと読みやすくなります。

逆に、ダラダラと情報を並べられていると、そのドキュメントは読みにくくなります。

例えば、こんな感じです。

- ページ速度を向上のために画像をキャッシュします
- ページ速度が遅くなっている原因としては、表示のたびに画像を取得しているためです
- 画像をキャッシュするためには、サーバのこの設定ファイルを修正します
こんな指示書がきたら、読むのにうんざりすること間違いなしです。。。

ドキュメントにおいて、情報の粒度、文章のパターンが揃っていると、人は次に来る文章を想像できます。

そうすると、読み手は読まなくていい部分を飛ばして、読みたい箇所に集中することができます。

良いドキュメントというのは、読み手にそれくらい配慮ができているのものなのです。

まとめ

今回は、【エンジニアの悩み】ドキュメント作りの3つのヒント、を紹介しました。

ドキュメントをどう書くか、は、どう考えているか、と同じといっても過言ではありません

ドキュメントを作るのが苦手なエンジニアは多いです。なので、これを機に周りと差をつけていきましょう。ぜひ、参考にしてみてください。

もっとドキュメントの作り方について詳しく知りたい人は以下の書籍がおすすめです。

また、SNSなどでシェアしてもらえると嬉しいです。