はじめに
未経験からエンジニアになってみて、コード以外に苦戦していることが多々あります。
詳しくはこちらをご覧ください。
薬剤師からエンジニアに転職してプログラミング以外で苦戦したことと対策
この中でも、特に頭を悩ませているのがドキュメントが書けないことです。
業務では、社員の方と要件について相談するときや、プロダクトの問題点を見つけて起票するときなどにドキュメントを書いているのですが…
これがなかなか難しいのです😭
何をどのような手順でまとめればいいのかがわからず、やたらと長くなったり、よくわからない文章になってしまいます。スピードが遅いのも課題です。
先輩からフォーマットをいただいたり、書き方を真似ているのですが、いまいちコツが掴めないでいます。
CEOに相談したところ、ドキュメントを書くときのポイントを教えていただいたので共有します🙋♀️
自己紹介
私は2023年9月1日にフロントエンドエンジニアとして自社開発のSaaS企業に入社しました。
未経験独学で、薬剤師からの転職です。
詳しくはこちらをご覧ください。
未経験独学で自社開発企業へ〜薬剤師からのエンジニア転職記〜
ドキュメントを書くときのポイント
- パターンを作る
- 誰が見てもわかるように具体的に書く
- 最初に背景を記載する
- 見出し、箇条書きで構造化する
- 一番大切なのは相手の目線に立つこと
パターンを作る
自分の中で 「このときはこの書き方！」というパターンを作っておくと良いそうです。
例えば、相談するとき、設計するとき、起票するときなど。
それぞれ書き方のフォーマットを作っておくことで、それに沿ってまとめることができます。
自分なりの書き方を習得するのは難しそうなので、まずは先輩からそれぞれのパターンに応じたフォーマットを共有してもらおうと思います。
誰が見てもわかるように具体的に書く
将来無関係の人が読んだとしても、理解できるぐらい具体的に書くということです。
確かに先輩方が書いたドキュメントはとてもわかりやすい…
これはなかなかコツが必要そうです。
私は具体的に書こうとすると文が長くなってしまう傾向があるからです😞
先輩からは、書き下しすぎと指摘されたこともあります。
いい塩梅を見つけたいです。
最初に背景を記載する
このドキュメントは、何について書いたものなのか？なぜやるのか？
背景を最初に記載して、読み手の頭に地図を作ることが大切だそうです。
確かに、ほぼ全てのドキュメントで背景が最初に書かれていました。
また、会議の時も同様に議題を読み上げた後にまずは背景を伝えていました。
Qiitaを書く時にも使えそうなテクニックです。
見出し、箇条書きで構造化する
まず、構造化とはコンサルにはお馴染みの考え方だそうです。
ドキュメントに書くときは、見出しや箇条書きを使うとうまく構造化できるみたいです。
なんだかわかるようなわからないような考え方ですね。
これは慣れるのが1番の近道と言われました😂
結局慣れかよ！と思いましたが…
物事を構造化して考えるとわかりやすいということだけでも、頭に入れておくと良さそうです。
一番大切なのは相手の目線に立つこと
いくつかポイントを紹介してきましたが、一番大事なのは相手の目線に立つことだそうです。
人は何かを伝えるとき、相手の目線になって話すことを忘れてしまいがちです。（※特にエンジニアは！）
話し手は前提も内容も全てわかっている状態ですが、聞き手は何もわからない状態で初めて聞きます。
話すときに聞き手の気持ちになることで、「この情報がないと意味わからないよな」「他の仕事もあるだろうし短時間で終えよう」などと想像して、お互いにとって気持ちのいいコミュニケーションができると思いました。
これは、前職の薬剤師時代のコミュニケーションで大事にしていたことと同じだと気づきました。
薬剤師として、薬局の窓口に滞在する限られた時間の中で、患者さんから必要な情報を聞き出し、それに基づいて薬の説明をしていました。患者さんの多くは医療や薬学の知識を持っていません。そのため、できる限り難しい専門用語は使わずに、他の言葉に置き換えて説明したり、全部を説明せずに必要な情報だけを伝えるなどの工夫をしていました。
相手の目線に立つことは、エンジニアだけでなく、どの職種においてもコミュニケーションにおいて重要なことなのだと思いました。
終わりに
ドキュメントを書く技術は、どの職種でも役立つはずです。
コードを書くだけでなく、ドキュメントも書けるエンジニアになりたいと思いました！
一番大切なのは相手の目線に立つことを忘れないようにしましょう。