sphinxでドキュメントを管理する
日本だけの風習かもしれませんが、開発の現場では仕様書をエクセルで作るのが慣わしのようになっています。セルをグリッドのように器用に使って作成している現場がおおいです。ただ、文書を書くということについてですと、非常に書くにくく、印刷したら端っこが切れて読めないとか、画面に見えているレイアウトと印刷したレイアウトがずれることは日常茶飯事です。私は基本的にmacな環境で仕事をしているので、このエクセルのドキュメントを見るのが苦痛にです。また開発中にわざわざエクセルを開いて無駄にメモリと時間を消費するのが馬鹿らしくなります。エクセルを立ち上げるのも面倒ですが、複数のファイルに分かれて書かれたものなんて中身の検索もままならず、どこに記述してあるのかすらわからない状態です。検索できないドキュメントほど使いにくいものはありません。また、納品のドキュメントもPDFで納品するとなると、わざわざ使いにくいエクセルでドキュメントを作成する必要もないと思います。開発の現場ではwikiのようなHTMLで確認でき、さらに好きなときに追記ができる、そして最後にはPDFで出力できるものが一番使いやすく有効なドキュメントです。
設計書のドキュメントについて
「社内監査」がなどドキュメントの体裁をうるさく言うところもあるようですが、本当に開発で必要なドキュメントはその時現場でできたドキュメントです。それはメモであったり、ホワイトボードに書いた内容であったり。この活きた情報をそのまま残すことが大切に感じています。設計書に書き直すと結論だけが簡潔に書かれるため、メモがきみたいな落書きが消されてしまいます。なにかあったときは、その結論いたるまでの課程が重要なので、あとで読み返すとなぜこの処理をしているのか理解出来ないことが多いです。
日本では内部監査がどうとか、ISOがどうのとよく耳にする話ですが、これらを取得したからしっかりした体制が出来ていると勘違いしている会社が多い。まわりからみているとこれらの認証を取得した結果、逆に今まで以上に無駄が増え、さらに品質まで落ちている会社が多いように思います。もう一度見直すべきでは？？日本を代表するトヨタ自動車がISOを取得していません。
話は変わりますが、microsoftが昔ほど元気がありません。windows中心で今までやってきた企業は、万が一、windowsがこの世から消えてしまうと大変な事になってしまいますよ。今の状況からすると可能性がないとも言い切れないと思います。
そのようなきっかけから、sphinxというドキュメント作成ツールを使ってみたいと思うようになりました。見た目も綺麗だし、機能もさり気無く豊富なので、このツールを使ってドキュメント作成を進めていきたいと思います。
プロジェクトの作成
sphinx-quickstart
必要なのはプロジェクト名、バージョン番号、著者の名前
