問題になりがちな開発ドキュメントに役立つサービス「Read the Docs」

新しく加わったプロジェクトで十分なドキュメントがない時、開発員は必ず「ドキュメントが無いので作業が順調に進められない」と考えがちです。 逆に、細かくしっかりとしたドキュメントがきちんと用意されている場合、まずそれを読まないと作業が進められないため、「こんなに膨大なドキュメントを読まないといけないプロジェクトは作業しずらい」と弱音を吐く人も少なく無いようです。 こうした事を解決しようと、家庭用電化製品などは、最近高性能機器となっているため、非常に分厚いマニュアルが存在しますが、そのマニュアルを読まなくても簡単に使い始められるように「簡易マニュアル」というのが付いているパターンが多いようです。 非常に日本人らしいやり方で「分厚いマニュアルのためのマニュアル」というマトリューシカのようなネスト構造になってきています。

開発ドキュメントはどこまで書くのが正解？

そもそも、開発ドキュメントがきちんと書かれているベンチャー会社など、そうそう存在しません。 何故なら今時のいけている会社というのは、開発してサービスをいち早く世の中に提供する事を目的としているため、開発員は、悠長にドキュメントなどを作っている暇は無い人が多いはず。 しかし、開発をした先に、運用、メンテナンスという領域になると、当初開発したメンバーしか知らない仕様が山のように存在するためにあとからプロジェクト参画した人は非常に困惑してしまうというのが、この「ドキュメントが無いんですけど問題」と思われます。 まあ、エンジニアというのは、無い物ねだりの人種なので、実際にドキュメントが存在していても読まずに文句ばかり言う人の方が多いんですけどね・・・orz しかし、ドキュメントが全く存在しないプロジェクトというのも怖くて仕方がありません。 基本構造や、そもそも何がどうなっているという程度の事は書かれていてもらいたいし、 これまでの運用記録として日誌やログなどがあるだけで、その後の同一トラブルなどの対応方法が明確になります。 初期開発した人がすでに会社をやめてしまっている場合などは、思い切ってサービスを一新して新たに作り直すという手段もありますが、きちんと内部を理解して、ドキュメントを作るという事で内容理解するという路線もあります。 少なくとも、「ドキュメントが無い」と言っていて、ドキュメント作成作業を進めていない担当者がいたら、その人は無能であると言われても仕方がないでしょうね。

オープンソースドキュメント集約サービス

WEB検索していると、OSP（OpenSourceProjectト）などのドキュメントがPDFで配布されているサービスに出会う事があります。 https://readthedocs.org/ このサービスは、名前の通りドキュメントが読めるサービスなんですが、自分でドキュメントを書く事もできます。 gitなどのリポジトリ情報と連携して、自動的にドキュメントを作って公開してくれるという機能も持っています。 まさにエンジニアの為のサービスと言えるでしょう。 詳しい使い方は、下記URLにて、日本語で説明してくれています。 https://rcmdnk.com/blog/2016/05/01/computer-brew-file-github/ 会社の商用開発のドキュメントをこのサイトで公開するのはそもそも難しいのですが、他サービスのドキュメントを読んで自分のドキュメントスキルの向上に役立てたり、実際に自分で作ったオープンソースのドキュメント構築に使うのもいいかもしれません。 ドキュメント作成もエンジニアの重要なスキルの一つですからね。