インフラエンジニアの津村です。
今回は、「ドキュメントは成長するもの」について、お知らせしたいと思います。

前回、「ドキュメントの読み解き方」「ドキュメントの内容についての質問の仕方」をご紹介しました。
今回は、その発展として「ドキュメントの更新の仕方」について、ご紹介したいと思います。

ドキュメントは成長するもの

ドキュメントは、システムのメンテナンスによっても成長しますが、内容的に「わかりづらい」「もっと適切な書き方がある」といった場合にも、成長をします。

「ドキュメントは本である」という事を前回ご紹介しましたが、本には「版」という考え方があります。要するに「バージョン」ですね。
よって、バージョンアップした際には、バージョンアップの概要を纏めて記載し（改版履歴）、バージョン番号の振り直し、そしてリリース（読み合わせ・レビュー・承認・展開）が必要となります。

ドキュメントのアップデートの例

例えば、以下のような表記があったとしましょう。
これでは、「コマンドを実行する」以外に何も情報がありませんよね。

　　---
　　手順3）
　　以下のコマンドを実行する。
　　「% ./deploy.sh」
　　---

これを、内容を読み解いて質問した結果を踏まえて、以下のようにアップデートします。

手順3）
手順2でgitリポジトリより展開したソースコードを、ステージング環境に展開する為、デプロイ用スクリプトを実行する。

手順2を実行した後、続けて以下のコマンドを実行する。

「$ ./deploy.sh」

実行後、以下の出力がされた場合、無事に処理が完了している。

「Deploy!!!」

ポイントは、以下の点を抑えることです。

• なぜ、コマンドを実行するのか
• どうやって、コマンドを実行するのか
• どのようになれば、処理が成功しているのか

改版の手続きの例

ドキュメントのWordファイルを更新した際、併せて改版履歴を更新します。

改版履歴の例

「いつ」「誰が」「何を変更して」「誰の承認を得たか」が抑えられていれば、問題ありません。
スッキリとまとめましょう。

なお、査読・レビュー前の場合、「査読社・承認者」の部分は、空欄にする場合が多いです。

レビューのやり方

一般的には、会議室などで「読み合わせ」をする場合が多いですが、Wordの標準機能「校閲記録」機能を使用することで、オンラインでもレビューが可能です。
以下は校閲記録を使用した例ですが、以下のように「変更履歴」「コメント」「返事」「承認」といった処理が可能です。

変更箇所を含め、全体を他のエンジニアに読んで貰うことで、「間違っている点」や「わかりにくい点」が明らかになる場合があります。

レビュアー全員が「ＯＫ」となった状態で、レビューは終わりです。承認者（上長など）に最終確認して貰い、「ＯＫを貰う（承認された）」上で、関係者に展開し、運用にフィードバックしましょう。

ここで、修正ポイントの指摘だけではなく、「どのように変更すれば良いか」というコメントも貰う事が出来ると良いです。

感情無きロジカルな世界

ここまでの作業で、実は「感情」というものは無く、「ロジカルなやり取り」が続きます。
ドキュメンテーションは、小説やマンガといったものではないので、淡々とロジカルな内容が続きます。
よって、レビューの際にも「感情」は入りません。

例えばレビューの際に感情が入ると、「ｘｘｘがわかりにくい」といったコメントや、「ｘｘｘが嫌だ」といった、受け取りづらいフィードバックが届きます。これでは、受け取った側も、どう処理して良いかわからないですよね。
レビューコメントの一例として、こういったスタイルを推奨しています。
「ｘｘｘが直感的に理解しづらいので、ｙｙｙという表記に変更しました。詳細は校閲記録をご確認ください。」

エンジニアである以上、ドキュメントは避けて通れない

現代では、ウェブ記事や書籍といった形で、様々な情報を受け取る事が可能です。これも一種の「ドキュメント」です。
しかし、現場固有の内容などはオープンには出来ませんよね。これらについては、現場ごとに別途ドキュメントを作成し、管理します。

ドキュメントがある事によって、複数人でシステムについて理解を共有する事も可能ですし、将来エンジニアが増える、もしくは入れ替わったとしても、良質なドキュメントがあれば、それらを継承する事が可能です。

「キャリテク！」は毎月セミナーを開催しています。
興味がある方は以下をご覧いただき、セミナーにご参加いただきたいです。
https://www.kcct.co.jp/careetec/