インフラエンジニアの津村です。
今回は、「ドキュメンテーションとは何か」「ドキュメントの読み方」について、お知らせしたいと思います。

よく、「ドキュメント読んで」といった指示は、現場で見かけますし、ある程度慣れてきたら「ドキュメントを書く」というタスクもよくあります。

しかし、「ドキュメントの書き方」って、意外と誰も教えてくれませんよね。
私も、何回も現場でレビューをされて身につけました。

まず、最初に「ドキュメンテーションって何だろう？」って事を、お伝えしますね。

未来のエンジニアにシステムを託すための「本」

「ドキュメンテーション」と言うと難しく感じますが、要には「取り扱い説明書」「仕様書」です。
これらを纏めて、現場では「ドキュメンテーション」と読んでいます。

例えば、データセンターにインフラを新規設計する場合、だいたい以下のようなドキュメントを用意します。

• 仕様書
• 設計書
• パラメータシート（各機器の設定を纏めた表）
• 構築手順書
• テスト手順書
• テスト結果
• 運用手順書

もちろん、中にはAnsibleのPlaybookやDockerfileといった、所謂「コード」を書けばそれで良い場合もありますが、現代の日本では、まだまだ少数派です。

「コードを読めばすべてわかる」という言葉もありますが、実際には適切なコメントが無く読み解きづらい場合や、相応のスキルを持っていない場合に全く読み解けないコードも多々あります。

よって、適切なドキュメンテーション（README.md程度）は必要でしょう。

ドキュメントに書く内容

もちろん、実際に「今どうなっているか」といった事が明示できると良いですが、もっと大切な事があります。それは、「設計思想」です。

• なぜ、このような設計になっているか
• どういった環境での稼働を想定しているか
• このシステムをリプレースするのは、どういった時か

こういった内容は、いわゆる「設計思想」となります。
これらは、エンジニアとしてスキルアップするにつれて、徐々に読み解いて行く事が出来る内容ですので、最初から理解しようとすると、とても大変です。

しかし、この「設計思想」が理解できた時、経験値（踏んだ場数）も上がっていますし、何より「なぜ、それが動くのか」（原理原則）が理解できている時だと思います。

ドキュメントの読み方がわからないとき

ドキュメンテーションは、小説やマンガの物語といったものと違い、ロジカルな内容しか書いてありません。
よって、落ち着いて時間を掛ければ、読み解く事が可能です。

例えば、最初に運用エンジニアとして配属された時、最初は定型作業を行う「運用オペレータ」というお仕事になるかと思います。
その場合、最初に「運用手順書」といったものが渡され、場合によっては先輩エンジニアの作業を横でチェックする「ダブルチェッカー」というお仕事から始まるかも知れません。
しかし、「運用手順書」の読み方がわからないと、先輩エンジニアが正しい仕事をしているか、画面を見ただけではわからないですよね。

私の場合、手順書を渡された時、最初に「赤ペンを片手に全部読み込む」という作業をします。
その上で、ゆっくりで良いので手順書を読み解き、「わからない点」「わかりづらい点」を整理していきます。
そして、整理が終わった後、手順書を渡した方と、認識の間違いが無いよう、確認をしていきます。

例えば、以下のようなものが挙げられるでしょう。

• このコマンドは、なぜ必要ですか？
• このスクリプトは、どんな処理をしていますか？

もし可能であれば、以下のような質問の仕方が出来ると良いでしょう。
「手順3の操作で、「./deploy.sh」とありますが、ステージング環境に開発中のソースコードをデプロイするスクリプト、という認識で合っていますか？」
ポイントは、「どこで」「何が」「どういう事になっているが」「この考え方で問題ないですか？（閉じた質問）」といった形にする事です。

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