ドキュメント作成が苦手なエンジニア！集まれ！

初めに

ユニファでバックエンドエンジニアをしている八木です。ドキュメント作成、エンジニアでは苦手意識のある人も多いのではないでしょうか。日常的に仕様書などを書く機会があれば練習になっていいのですが、そうでない場合や、初めて仕様書や手順書を書く場合など、戸惑いながら真っ白な画面を見続けている人もいるのではないでしょうか。

本記事はエンジニアのみなさんの中でのドキュメント作成への苦手意識を少しでも減らしていけたらいいなと思っています。初めてドキュメント作成をするような初級者向けの内容です。ドキュメントの骨組み作成までの道筋を記載しています。

今回は例にとってユニファが提供している「ルクミー連絡帳」というサービスを紹介するドキュメントのアウトラインを作成してみたいと思います。

1.いいドキュメントとは何か

エンジニアがドキュメント作成する際は、何かの仕様書だとか手順書だとか、作らないといけないものが決まっていると思います。この時点で書かないといけないテーマはあるのですが、悩みの種としては

どこから手をつけたらいいかわからない
何を書いたらわかりやすいのかわからない

というのが大きな悩みの種になると思います。「読みやすい、いいドキュメントにしたい」と思っているが故の悩みですね。では、読みやすいドキュメントとはどんなものでしょうか。普段様々APIドキュメント等を見ている我々エンジニアには覚えがあると思います。

簡潔でわかりやすい
- 明瞭な表現
必要なことだけ記載されている
- どこに何が書いてあるか理解できる
- 要点が先にある
- 話の流れが見える

この2点は絶対に抑えたいところです。ではこの2点の要点をクリアするためにはどんなドキュメントであるべきでしょうか。

私は以下の2点であると言えると思います。それは

読み手の意識
ドキュメント全体の設計

です。読み手の意識も設計も、エンジニアがコーディングする際とかなり共通点があります！順番に見ていきましょう。

2. 読み手を意識しよう

テーマ作り

他の人が理解できるものを書く、というのはプログラミングにも通じます。このコードを保守しているのがたとえあなた一人だったとしても、６ヶ月後のあなたはもはや覚えていないかもしれません。もしくは新しい人が会社に入社して一緒に保守してくれるかもしれません。というような思いも下敷きにあり、我々エンジニアは読み手に対して読みやすいコードを書くことが通例になっていますよね。

ドキュメント作成も同じで読み手の意識が大切です。文章全体を読みやすくするためにも、まず何を書くのかのテーマを決めた後は、明確な「読み手」を設定しましょう。たとえばですが、読み手がエンジニアに限定される場合はIT専門用語をたくさん使った方が読みやすいドキュメントになりますが、読み手にエンジニア外が含まれる場合は、なるべく排除した方がわかりやすくなります。このように文章全体の雰囲気を定めることになるので、必ず明確に設定しましょう。

今回は「『ルクミー連絡帳』というサービスを紹介する」というテーマでドキュメント作成をしますが、これではまだ読み手の意識が足りません。なので、ユニファのサービスの一つ、「『ルクミー連絡帳』を全く知らない、新しく入社した人に簡単に説明する」、というテーマで作成します。

3.設計してみよう

コードを書き始めるより前に設計を行うことは、大きな機能であればあるほど重要です。機能の適切な分解は開発や修正を簡単にしますし、分解することで実装工数の見積りを可能にします。

これをしないと

パッと見た印象で何をしているソースコードなのかわからない
ソースコードが共通化されておらず、同じようなソースコードが至る所にある
見積りより多くの実装工数がかかる

といった問題が起こりやすいです。ドキュメントも同じで、文章を書く前に設計を行うことで、ほとんど同じような問題を解決することができます。設計を行うことで、

何を伝えたいのかを理解しやすくする
同じ話を何度もすることを防ぐ
ドキュメントを書く時間を減らす

といってた素敵な効果があります。ドキュメント作成の際は設計から始めましょう！

コーディングとの共通の文化

関数名は大事

内容を簡潔に示した関数名をつけることは、シンプルなコードを書く際に役立ちます。ドキュメント作成に当てはめると関数名は「見出し」になります。簡潔な見出しがつけれるような設計にしましょう。

コードの共通化

同じことを複数の場所に書くと、コードの変更が必要な場合に、全ての箇所を修正する必要があります。これを防ぐためにコーディングではしばしばコードの共通化を意識しておこないます。ドキュメント作成も同じ問題が発生します。複数の場所に記載するとメンテナンスが複雑になり、古くて利用できないドキュメントも生まれやすくなります。共通化できる箇所は共通化し、必要な場所には参照リンクを貼りましょう。

ーー

このように、ドキュメント生成にはコーディングとの明確な共通点があります。普段馴染みのある共通点を聞いていると、できそうな気がしてきませんか？コーディングと同じように設計もやってみましょう。

ドキュメントの設計

テーマ分解　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　

テーマを構成する要素は基本的に2w1hで分けることが可能です。このように大きく３つに分けてから、さらに細かく分解していきます。

たとえばとある機能の要件定義書を作成する場合

なぜ(why)
- なぜその機能が必要なのか
何(what)
- その機能はどんなものなのか
どうやって(How)
- どうやってそれを使うのか

アウトライン

このテーマ分解をもとに「『ルクミー連絡帳』を全く知らない、新しく入社した人に簡単に説明するドキュメント」のアウトラインを作成します。この際に、読み手は『ルクミー連絡帳』を全く知らない人を設定しているので、機能名などをなるべく簡潔に説明しながら、見出し設定を行います。

ルクミー連絡帳（デジタル連絡帳サービス）概要

# 機能の利用目的(なぜ)
1. 欠席予定やお迎え時間の変更など、保護者からの連絡をスマートフォンやパソコンからまとめて確認できる。
2. クラス共通の内容は全員の連絡帳に自動反映。
3. ルクミーフォト(自社他サービス)と連携し、今日の自分のクラスの写真の選択・添付も簡単。保護者への「保育の見える化」ができる。
4. 体調やケガの連絡などは、保護者に個別メッセージを送信。電話をかけるか迷う場合の連絡も気軽に連絡できる。
5. 大切な記録を紛失する心配も不要になる。

# 機能の全体像（何を:どんな機能か）※例に挙げているのは機能の一部です
1. 園児ごとの連絡帳を作成する機能
　⚪︎機能詳細
2. 保護者と園間のDM（個別連絡）を作成する機能
　⚪︎機能詳細

# 機能の使い方（どうやって）
1. 園児ごとの連絡帳を作成する機能
　⚪︎操作方法
　⚪︎画面
2. 保護者と園間のDM（個別連絡）を作成する機能
　⚪︎操作方法
　⚪︎画面

何を（what）の中で今回は二つの機能をあげ、その機能を示す「見出し」をつけました。こうすることでパッ見た際に構成がわかりやすくなります。

何を（what）でつけた見出しをしたじきに機能の全体像（How）を設定できました。ここでは機能詳細と操作方法を分けることで同じことを何度も説明することを避け、また構成が「何を（what）」と同じになっていることで全体的にわかりやすい構成になっています。

このようにしてドキュメントの骨組みを作ることができました！

どこに何を書けばいいのかが決まることで、文章が圧倒的に書きやすくなりました。後はこの詳細を記載していくだけです。今回はアウトライン作成までの記事なので割愛します。

最後に

ドキュメントのアウトライン作成についてみてきました。細かくテーマを分解する大切さやわかりやすいテーマ名をつける大切さはコーディングにも通じるところがありますね。いつものコーディングとの共通点を見出すことで、少しでもドキュメント作成のハードルが下がれば幸いです！

ユニファでは開発の助けになるよう豊富なドキュメント作成の文化があります。一緒に新しい保育を模索してくれるエンジニアを募集中です！

jobs.unifa-e.com

ユニファ開発者ブログ

ユニファ株式会社プロダクトデベロップメント本部メンバーによるブログです。