ドキュメントが苦手なプログラマーに聞いてもらいたい話

ドキュメントを制するものはシステムを制す、を信じ始めた、ユゲタです。 スタートアップのIT企業って、まずドキュメントは後回しになります。

ドキュメント無しシステム構築昔話

多くの場合、まず出来るか出来ないか？という課題に対応する為に、闇雲にシステムを作り、 それが市場で受け入れられるのか？ということに対して、公開してさまざまな計測や、市場調査などを行います。 この時点で、「このサービスいけるぜ！」となったらシステムのリファクタリングや、機能追加、アプリなど他のプラットフォームなどへの展開を行い、事業拡大をしますが、 あれ、「ドキュメント書く暇無くなったぞ」と、エンジニアはふと気が付きます。 でも、そんな時に経営者からは、ドキュメントを書く作業よりも、もっとシステムを作ってほしいと要望されてしまいます。 こうして、ドキュメントの無く動き続けるシステムは世の中に誕生して、放たれて行くことになりましたとさ。

ドキュメントって一体どのレベルで必要なの？

一言で言うと、インターネットサービスを利用しようとした時に、規約にサインをしたり、チェックをすると思いますが、ああしたレベル以上に必要です。 よく、「プログラム内に、コメントを書いてあるから、プログラマーが読めば分かるはず」というエンジニアもいますが、 とんでもないアホプログラマーですね。 こんな、プログラマーがプロジェクトリーダーをしたとしたら、とんでもない結末を迎えてしまいます。 ドキュメントをプログラムコードのマニュアルとしてしか、認識できていない証拠ですね。 ここで言っているドキュメントは、「サービスを継続させる為に必要なドキュメント」というのが最低限の定義になります。 なので、どのレベルでドキュメントが必要かと言ったら、理想はプログラミング初心者が、サーピスプロジェクトにアサインされた時に、理解できるレベルです。 「細かなプログラムの説明なんか書いてられない」と言う場合もあるかと思うので、最低どのスキルを保持しているかを明記することで、ドキュメントが読める最低レベルを定義しても良いでしょう。

ドキュメントってどのくらいの時間をかけて作るものなの？

これは、とあるインターネットサービスを運営している会社で、ドキュメントが無く、肥大化したシステムの為、誰も内部理解ができず、 人を採用しても、すぐに離脱をしてしまって困っている会社の人たちにアドバイスをした時に聞かれた質問です。 プログラマーは、ほとんどの人がドキュメントを書き慣れていない為、プログラミングの構築時間は算定できても、ドキュメントの構築時間は算定できない人が大半です。 しっかりとしたドキュメントを作る時間算出なんて出来るわけないですよね。 なので、この時のユゲタの解答は、「開発、プログラミングをした時間と同じ時間は掛かると思いましょう」と言っておきました。 少なくても、詳細ドキュメントを外部会社に依頼したとしたら、開発コストよりも多くの見積が出て来て、ビックリした経験があるので、あながち間違ってはいない考え方だと思います。 もし、それよりも早く出来るのだとしたら、コストを支払う経営者にとっても、プログラマーにとってもいい事だし、 それよりも長くかかってしまうとしたら、プログラミングをしているけど、人に説明ができない、作り投げしている、適当なシステムであると認識するべきですね。 なので、普段の作業で、一日中プログラミングをしたとしたら、半分はやった事のドキュメントを書けば、うまくいくはずです。 実際にやってみると、１日作業で、7時間プログラミングをして1時間やった事のまとめを書く、と言うふうにすれば、ドキュメントコストはかなり削減できるというのは、ユゲタの経験談です。 もっと落とし込んで、一つの作業で、頭の中がホットな間にドキュメントを書くことができれば、もっと効率的になることは間違い無いでしょう。

実際どういうドキュメントを書けばいいの？

普段ドキュメントを書き慣れていない人が、最も困るのがこの点でしょうね。 書き慣れていない人に、この手の話をすると必ず質問をされる内容です。 まず、基本的に開発ドキュメントに限らず、ブログでも、SNS書き込みでも、どれも基本的に、ドキュメントには基本的なルールがあり、 「読む人（ペルソナ）を定義して、文章を書く」という事です。 でも、開発ドキュメントで間違えやすい点として、同じ開発チーム内にいる人に向けて書くというドキュメントになると、ほとんど意味のないドキュメントになりがちなので、 考えるべきは、「システムを誰か別の人に継承させる時に必要なドキュメント」と言う風に考えると良いでしょう。 このように定義すると、そのチームに新しい人が入って来た時や、外部の会社に開発を委託する時、人員拡大で、プログラム初心者がチームに参画した時、何かしらのシステム検査で第三者機関が調査をする場合、 こうした時に、そのドキュメント一つで全て対応することができます。 ここまで読んだ人は、どういうドキュメントが必要なのかは理解できたかと思いますが、実際のところ、何のドキュメントを作れば良いかは、全てのシステムによって異なるので、最低限のルールとしてお考えください。

最後に

メチャクチャ偉そうにドキュメントについて書きましたが、かつてのユゲタは、とある、ベンチャー会社を株式上場する会社まで開発を行いつつCTOをやって来たんですが、ドキュメントは一切書かない、アホプログラマーだったんですね。 なので、ドキュメントなど無くても会社は大きく出来ると言う経験と、今頃になって、ドキュメントの必然性に気が付き、 コンサルティングとしていろいろな会社の開発部門に行ってみると、ほとんどの会社がドキュメントが作られておらず、人員教育、開発拡大、システムリニューアル、などで無駄な思考と労力を掛けているじったいに気が付きました。 改めて、優秀なプログラマーというのは、しっかりとしたドキュメントが書けるプログラマーであると考えても良いかと思うようになりました。 もし、この記事を真剣に読んでくれてた人がいたら、あなたは、開発チームに属していて、ドキュメントが無くて困っている（困っていた）人だと思いますが、そのチームのプログラマーの皆さんの思考は、ドキュメントに向いていますか？ ドキュメントをないがしろにしたら、その後シッペ返しを喰らってしまいますよ。 素敵なプログラマーライフに乾杯！