意外と大切なドキュメンテーション!(2/2)
ドキュメントは成長するもの
2018年12月19日

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

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

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

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

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

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

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

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

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

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

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

「$ ./deploy.sh」

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

「Deploy!!!」

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

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

改版の手続きの例

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

改版履歴の例

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

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

レビューのやり方

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

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

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

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

感情無きロジカルな世界

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

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

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

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

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

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

執筆者:津村彰
- Akira Tsumura - 合同会社リトルビッツ ファウンダー・CEO
「日本の中小企業の情報システムをカッコよくしたい!」という想いから、プライム・ストラテジーを卒業したその年に起業。 普段は「情シスコンシェルジュ」として、中小企業の情報システム部門改善を中心としたインフラ整備・業務改善を日々行っている。1997年に自作サーバでサーバ公開を始めて以来、パブリッククラウドの登場とLet'sEncryptの登場、KUSANAGIの登場は、日本のウェブ界を大きく変えたと思っている。プライム・ストラテジー時代は、MSP事業部にて大手顧客を中心とした要件定義・実装・運用改善を担当。データセンタからパブリッククラウドまで、サーバサイドの様々なインフラ構築や最適化を担当する。
掲載されている情報は、発表日現在の情報です。最新の情報と異なる場合がありますのでご了承ください。

ページの先頭へ戻る