ドキュメントについて

主にシステム開発に携わる際、ドキュメントはみなさんどうしてますか?

Excel方眼紙
Wordで納品時に一気に書く
チケットに全て書く
ドキュメントは書かない
Wikiに書いている

皆さんいろいろでしょうが、自分は2003年ぐらいからずーーーとWikiに書いてます。納品物も基本Wikiです。お客様によっては文書の内容より体裁を求められる場合も多かったので、体裁だけ整えるためにWikiの内容をExcel方眼紙にコピーペーストして納品したこともあります。が、なぜWikiにこだわっているか、何が良いのかをお伝えできたらと思います。

ドキュメントの問題

たいてい、以下のような問題が発生しているのではないでしょうか。

古くて使いものにならない
何が書いてあるか理解できない
期待する情報がない、どこにあるかわからない

サラッと書きましたが、せっかく作ったドキュメントが有効利用されることって殆ど無いですよね。「あ、ここの仕様はどうなっていたかな」と思っても上記のような問題に直面し、結局ソースコードを眺めたりテスト環境で手間ひまかけてテストデータ投入して再現させて確認したりという状況ではないでしょうか。

なぜドキュメントは維持されないのでしょうか。

仕様ではなく設計書を作成している

システムは運用が開始されてから初めて価値がでます。そして価値を高めるためにたいてい機能追加や改修が行われます。もちろん不具合対応も多いでしょう。そのときに過去のドキュメントを修正することは殆どないようです。新しい設計書を作成するか、チケットだけで管理するか、そんなケースが自分の周りではほとんどでした。

よくよくみると、過去の仕様書も仕様書というよりは設計手順書というべき内容が書かれているケースも多々ありました。どうやって作るかにばかり着目していて、何を作ったか、どうして作ったか、何が得られるか、などはあまり記載が無いことも多いようです。どうやって作るかは開発時には有効だったかもしれません。しかし、運用が始まってからは意味のない資料となることがほとんどです。逆に意味のあること(何を作ったか、どうして作ったか、何が得られるか)などは書いていないので、あとから確認しようとしてもさっぱりわからない、ということになります。

たまに「ソースコードを見れば良い」とか「動かせばわかる」という意見も聞きますが、「なぜそうなっているか」の理由はわかりません。どう動くかだけがわかります。また、全体の関連や複雑な条件で発生する事象は動かしたくてもなかなか動かせません。だいたいその仕様を知らなければ再現すらできないことも多いと思います。

ドキュメントの修正は面倒

また、一度納品時に完璧に仕上げた素晴らしいドキュメントは直したくないものです。ただ上述の通りシステムは生きているのでどんどん姿が変わっていきます。その内容を完璧なドキュメントに反映するには、大変な労力がかかります。

特にExcel方眼紙は、改行位置などを手動で入れることが多く、文章の挿入/削除/修正はとてもやりづらいですね。

また画面仕様書など事細かに吹き出しやマークをつけてわかりやすい図を添付していると、ちょっと項目が追加になっただけでスクリーンショットを取り直し、吹き出しをまた適用していかないといけなかったりします。ドキュメントを作る際には、「良いものを作ろう」「わかりやすく書こう」という意識がはたらき、素晴らしいドキュメントを作るのですが、それは極めて修正しにくいドキュメントとなってしまいます。

どうしたらドキュメントを維持できるのでしょう

Wikiを使う

まず簡単な対策としてWikiを使うことです。Wikiを使う理由は以下です

修正しやすい
難しい書式が使えない
共有される

仕様書がWikiに書いてあれば簡単に検索できる場合が多いでしょう。ローカルファイルのIndexを使うよりは高速に目的文書を見つけることができると思います。

また、WordやExcelで文書管理していると、たいてい巨大な文書になり、修正は全文書を一遍に修正対象としてしまうので、修正がしにくいですね。Wikiの場合は長い文書を書くことは少ないでしょう(書きにくいから)。それに複雑な書式もまずかけません。そのため、単純な文書をリンクを使って書いていくことになると思います。修正はその一つの文書のみ修正していくので修正が局所化され使いやすいはずです。Dokuwikiなどはブロック編集もできるのでさらに使いやすいですね。

人の目にさらされやすい状態

Wikiを情報集約の基盤にすればWikiを常に参照する機会が増えます。自分は朝会の内容を事前にWikiに書くようにメンバー全員に依頼していますが、そうするとメンバーは毎日Wikiを参照、書き込むことになります。つまりWikiを常に使っているので、Wikiに記載されている仕様を見る機会も増えるというものです。

これがWord/Excelだと、フォルダ移動してファイルを見つけ出して開かないと内容が確認できないので、かなり能動的に開こうと思わない限り開いて確認することはないと思います。しかしWikiの場合、常に参照/書き込みする癖がついているので、ページ一覧などに仕様のタイトルがあると、「あれどうだったかな、ちょっと確認してみよう」という気持ちも起きやすくなります。そして、そこで情報の欠落や不具合に気づいたらその場でその人が修正ができる、という流れになります。

つまり、

Word/Excelの場合、「強く確認が必要」と思わないと開かないので、修正されにくくなる
Wikiの場合、「ちょっと確認しよう」という場合でも参照されるので、修正されやすい

ということです。

ドキュメントの共同所有

小説や論文は執筆者が最後まで責任をもって書くと思いますが、それは書きあげたら変更がめったに起きない文書だからです。システムについてのドキュメントはシステムとともに変更され常に変化していく必要があるので、個人管理では限界があるのです

たいていのプロジェクトでは、この仕様書はAさんが書いたのでAさんが直すべき、という暗黙ルールがあったりします。が、継続して維持される文書を個人に特定して管理するのは無理があります。それよりは、

気づいた人が
気づいた時に

修正すれば仕様書が最新状態を維持しやすくなります。

「レビューはどうするのか?」「勝手に修正すると間違えた内容が書かれる場合もあるのでは?」という意見もありそうですが、そんなことをためらっていては最新情報を維持管理はできません。多少間違いが合っても良いぐらいで、メンバー全員が文書に責任を持ち、維持修正に積極的に関わる、としなければ常に文書は古くなっていくでしょう。

もちろんレビューをしたり、事前確認が必要な場合もあるでしょう。その場合は、自分は朝会で毎日共有するようにしています。

また間違えた修正をしたところで大した問題ではないです。Wikiは履歴管理されているので、いつでも元の文書を復活もさせられます。

お客様ともリアルタイム共有

Wikiなのでお客様にも公開できます。書きかけの状態をお客様に見せるわけにはいかない、という意見もありますが昔の価値観と思います。お客様はやはり最新の維持されている正しい情報を求めているはずです。

正しく書き上げるまで大事に社内でとっておいて、レビューをしてから公開したい

こんなことをしていたら、次に修正するときも同じ手順が必要で、結局修正がどんどん遅れ、最終的には古い文書が遺跡として残されていくことになります。

どこまで管理するかは微妙ではありますが、自分は定例会議などで、「ここまでは書き終えた」とか「現在XXXはまだ見ても意味がないです」ぐらいは伝えています。進捗管理で厳密に管理したければそれもよいでしょうが、大事なのは書きかけであれ常に公開する、という意識を持つことです。お客様に「XXXが間違えている」と言われたら「ありがとうございます、直しますね」とか「そこの修正はまだ未着手です、少しお待ち下さい」で良いと思います。修正手順にこだわりすぎるのは、完璧に仕事をこなそうとするあまり最低限の情報すら残せなくなってしまう危険性のある状態、だと思います。

常に公開、いつでも見てね、不具合あったら教えてね

こんな感じですすめていけば結果的に最新情報が常に維持されやすくなります。

完璧な文書は書かない

真面目な人ほど、わかりやすく完璧な文書を作成しようとしますが、重視するのは将来に渡って情報が維持管理されるか、です。システムが生きている以上ドキュメントも完成はせず、システムと同期をとって変化していくことを理解しなければいけません。完璧で誰もがわかりやすく、読みやすい文書を作るとそこで燃え尽きてしまい、それ以上の修正をしたくなくなります。また、修正しようとしても同じレベルを維持しようとすると多くの工数を修正工数に割かなければならなくなります。

自分はここまでドキュメントに言及しているのですが、実はシステムにとってドキュメントはそれほど大事だとは思っていません。動くシステムのほうがずっと大事です。ただその動くシステムを維持するために最低限のドキュメントがあるととても楽ができるので、必要最低限の情報だけ維持管理できることを重視しているというわけです。

もちろん将来を考慮するため、現有メンバーの暗黙知に頼るのは正解ではないです。ただし、万人にわかるような資料を書くことも不要です。若干の補足説明や動くシステムがあればわかるようなことは書かず、わからないことだけを簡略に書いておく、ということが大事です。もちろんレベルは様々、人によってもわかりやすさは異なるでしょう。なので、チーム全員で必要なレベルを常に意識しながらドキュメントを共同管理することが大事なのです。

そしてそれができる最善策が、「Wikiを使う」だと思っています。

まとめ

設計手順書は書かない、仕様を書く
ドキュメントは共同所有する
気づいた人が、気づいた時に、即修正する
完璧な文書は作成しない、維持しやすい文書を書く
上記を実現するにはWikiが最適

補足

文書といったりドキュメントと言ったり表記ゆれがでていますが、どちらも同じ意味です。ご容赦ください
自分の周りではWikiの仕様は一般的になりましたが、数年前までは異質で、よく非難/批判されたものです
一部の開発現場では未だにExcel方眼紙だと聞いたので書いてみたくなりました
すべてのドキュメントをWikiで書く必要があるという意味ではありません、Excelやその他ツールも一部併用しています
何を書くかには言及していませんが、全体構成やサービス連携などの図も必要な場合が多いと思います
マイナビニュースドキュメントを最新に保つ効率的な管理方法とは? にも同じ内容を投稿しています