意外と大切なドキュメンテーション!(1/2)
ドキュメンテーションってなに?
2018年12月19日

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

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

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

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

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

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

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

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

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

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

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

ドキュメントに書く内容

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

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

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

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

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

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

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

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

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

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

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

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

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

ページの先頭へ戻る