このエントリは、パッケージソフトウェア開発 Advent Calendar 2014 の 7 日目の記事です。
はじめに
普段、仕事でパッケージソフトウェアを作っています。
具体的には、DataSpider Servista という EAI（Enterprise Application Integration）で、ざっくり数十万～数百万円くらいする、企業向けのソフトウェアです。
パッケージソフトウェアの開発
パッケージソフトウェアの開発というのは、既存ユーザや（特に企業向けソフトの場合）見込みユーザの要望を適宜取り入れながら進めます。
多くのユーザに使ってもらうパッケージなので、単に特定のユーザの要望を満たすだけではだめで、製品の戦略や設計思想、また互換性にも配慮しつつ、仕様を考える必要があります。
使いやすさ、UI/UX のよさというものも忘れるわけにはいきません。*1
Design Doc を書いてみよう
僕が所属するアプレッソという会社では、現状、仕様策定プロセスとかフォーマットとかがあまりきっちりとは定められていません。*2
そんな環境で、9 月頃にちょっと大きめの新機能を開発することになりました。*3
先ほど書いたような色々なことのバランスを取りながら、使いやすくて、便利な新機能にしたい。
さてどうやって進めようかな、と考えたときに、Design Doc を書くのがよいのではないか、と思い至りました。
それから実際に Design Doc を書いてみて、やがて開発が完了し、振り返ってみてトータルではなかなかよかったと思うので、次に大きめの開発をするときにもまた書こうと思っています。
このエントリでは、Design Doc を書いてみてよかったところ、イマイチだったところについてそれぞれ書いてみます。
Design Doc とはなにか
その前に、そもそも Design Doc ってなんなのってところについて簡単に説明しておきます。
何を・なぜ・どのように作るか
Design Doc というのは、ごく簡単に言うと、ソフトウェアについて「何を・なぜ・どのように」作るかを示したドキュメントのことで、「Google の Design Doc」として数年前に話題になっていました。
UML や XDDP の USDM（参考 : USDMについて書かれたネット上の資料 - たまゆら雑記）などと比べると、要求・仕様・設計について考え、ドキュメント化するための手法という点では共通しますが、具体的な記法までは定義されていないことが一つの特徴と言えそうです。
記法がきっちり決められていないぶん、「要求仕様」みたいなものをはじめから完全に文書化することが難しい（あるいは、するコストに対してするメリットが見合いにくい）パッケージソフトウェアの開発に使いやすいのではないかと思います。
考えるための道具
また、「コミュニケーションのための、コードに先立つドキュメントとしてきっちり作り込み、先々もきっちり保守していく」というよりは、「開発者自身が考えるための道具」という面の方が強いかもしれません。
Design Doc のそういった側面については、伊藤直也さん（@naoya_ito）の以下のエントリでも触れられています。
その他、詳細
その他、Design Doc の詳細については、以下 2 つのエントリに目を通してもらえれば、どういうものかよくわかると思います。
特に 2 つめは鵜飼さん（http://ukai.jp/）をはじめとした Google 社員が書いた WebKit Web Socket の Design Doc に触れたもので、具体例として参考になります。
実際に書いた Design Doc の目次
これから書くことの背景をイメージしてもらいやすいように、今回僕が書いた Design Doc の目次を転載しておきます。
目次を作るにあたっては、以下の記事を大いに参考にさせていただきました。
よかったこととイマイチだったこと
では、実際に書いてみてよかったことと、イマイチだったことについて述べていきます。
よかったこと
まずは、よかったことです。
開発初期は、設計資料、実装のためのマスター資料として大活躍した
Design Doc には、「何を・なぜ・どのように」作るかを示します。
この「何を・どのように」作るかを予め文書化しておくことで、基本的に「次に何をやればいいか」が Design Doc を見ればわかる、という状態になっていました。
そこそこの大きさの機能の開発で、変更コンポーネントも複数に渡り、さらにはじめて触るコンポーネントも少なからずあったため、もし Design Doc がなかったら、開発の各局面でたびたび立ち止まることになっていたと思います。
このメリットは、もちろん、事前に要求仕様書を作成し、UML でユースケース図、クラス図、シーケンス図といったものを作成した場合にも得られただろうと思いますが、ドキュメント作成にかかる工数は文字通り桁違いです。
Design Doc の場合、「事前にほんのちょっと時間をかけてやることをまとめておいただけで、そのあとの開発がとてもスムーズに流れた」という感覚でした。
特に、今まで触ったことのない機能の変更箇所確認に役立った
Design Doc の「どのように」作るか、という部分について、何を、どこまで書くかというのも色々とやりようがあるとは思います。
今回、今まで触ったことのない機能を追加するにあたって、過去に類似の機能追加を行った際のコミットログを参考にしました。
過去のコミットログを読むことで、ある機能を追加したいときに、どのコンポーネントをどのように変更すればよいのかがわかります。
しかし、開発にあたってその都度コミットログを参照するのは面倒です。
そこで、開発中に都度ログを見るのではなく、計画段階でログを整理して、各コンポーネントでの変更箇所・変更内容をまとめておきました。
これが、目次の「実装」の部分にあたります。
具体的には、変更すべきファイルの名前と簡単な変更内容、新たに作るクラスの（仮の）名前や役割を記述し、必要な箇所ではインタフェースを定義しました。
このことによって、当該機能の開発中は、
- Design Doc を見る→書いてあることをやる→Design Doc を見る→……
ということの繰り返しで、快調に作業が進みました。
ただ、ある機能を初めて改修する人が毎回こういう（課題管理システムで適当な課題を見つけて、コミットログを分析して……みたいな）作業をやるべきかというと微妙な気もするので、開発ガイド的なものを書けたらいいな……とも思います。
スケジュール表としてもそこそこ役に立った
Design Doc にスケジュールを書き込むのは一般的ではなさそうですが、試みとして、スケジュールも Design Doc に書いてしまうことにしました。
このスケジュールも随時アップデートすることで、自分の現在位置を把握するのにそこそこ役立ったと思います。
僕が所属する組織では、（場面にもよりますが）プロジェクト管理ツールを使ったスケジュール管理みたいなことはあまり行われていないので、自分で管理する必要があります。
この開発を自分の一人プロジェクトと考えたとき、Design Doc はとにかく随時見るし、割と更新もするので、情報を一箇所に集めるという意味で、スケジュールを乗っけておく場所としても案外便利に使えました。
ただ、Design Doc がスケジュールを掲示しておくのにベストな場所かというと、そうとも限らないかもしれません。
Design Doc は（少なくとも Markdown で書く限り）ほぼプレーンテキストでしかないので、表現手段が限られます。
そういうわけで詳細なスケジュールまでは書き込まないことにするとしても、マイルストーンを一発載っけておくのは有用だと思います。
イマイチだったこと
続いて、イマイチだったことについて書きます。
開発の後半から終盤にかけて、更新されなくなった
Design Doc を知るきっかけになった MIJS のシリコンバレーツアー報告会というイベントがあったのですが、そこでは、「Design Doc はコードや仕様の変化に合わせてガッチリ保守したりはせず、どちらかというと作り捨てに近い（と思われる）」といったことが言われていました。*4
しかし僕は、「いやいや保守したほうがいいんじゃないの」派だったので、できるだけ保守するようにしてみました。
実際、保守しているあいだはその労力に見合ったリターンがあったと思います。
……が、保守の微妙なメンドさ *5 や、開発終盤のキビシさ *6 により、最後の方はほとんど保守できていませんでした。
（途中までは保守を続けたのに）結局「あとから他人が見るためのドキュメント」として考えたときに中途半端なものになってしまった、というのが、ちょっと気になるところではあります。
とはいえ、どの部分がまだ有効かは保守している本人で判断できるので、「まだ有効な部分だけを資料として拾っていく」のには、終盤まで十分役立ちました。
役に立つ部分が残ったのは、まさに（途中までとはいえ）保守を続けたからであって、保守を続けるメリットがないとは言えないと思います。
なお、一人で使う場合は好きなところを好きなように保守する、というスタイルも取れますが、複数人が参照し続ける場合は、どこを保守して、どこを捨てるのか（あるいはぜんぶきっちり保守するのか）を決めておかないと、ややこしいことになりそうです。
更新が案外メンドかった
プレーンテキスト信者なので Markdown で書いてみたのですが、エディタ・ビューアがなくても読めるように HTML でエクスポートして、課題管理システムに随時上げて、みたいなことをやってたらなかなかメンドかったです。
せっかくプレーンテキストにしたものの、結局、バージョン管理もしていません。*7
これはツールで解決（ないし、少なくとも改善）できる部分かなと思います。
具体的には、Qiita:Team！ Qiita:Team がほしい！！
でも、Google ドキュメントもアリだな、と最近思い直しています。
Google ドキュメントも適当にバージョン取りながら保存とかしてくれるし、人に見せるのも簡単だし、思いのほか使いやすいし。*8
他には、Wiki（あるいは Google サイト）というのもよいですね。
GitHub を使っていれば、Gists というのも選択肢に上がりそうです。
結局一人でしか使わなかった
Design Doc には情報共有ツールとしての側面があるはずなのですが、なんだかんだでほとんど一人でしか使いませんでした。
これもやっぱり、「ここにあるんで見てください」って気軽に言えるような置き方になってなかったのが、案外大きいんじゃないかなと思っています。
この問題も、Qiita:Team や Google ドキュメントを使うことで解決できますね。
「テスト計画」、あんまり見なかった
「テスト計画」という項目を設けて、開発初期に「どういうテストをするよー」みたいなことを書いたのですが、結局、なんかあんまり見ませんでした。
- 内容が中途半端というか、「そりゃやるだろ」みたいなアタリマエのことしか書いてなかったこと
- なんか文字がいっぱいで見るのしんどい感じだったこと
あたりが原因かなと思っています。
次書くときは、ちょっとそのへんを意識してみようかなと思います。
まとめ
Design Doc を書いてみて、よかったこと、イマイチだったことについてつらつらと書いてきました。
よかったこと、イマイチだったこととそれぞれあったのですが、イマイチだった部分はより改善したい部分という感じで、トータルでは、かけたコストに比してとても役に立った、というのが素直な感想です。
このエントリでは触れられなかった項目もたくさんありますが、やはり全体として、これからやること、今やっていることの全体像と細目の両方がペライチのドキュメントにまとまっているということの安心感はかなり大きいです。
イマイチだった部分を改善しつつ、また大きめの開発をやるときには Design Doc を書こうと思っています。
おまけ : ペルソナ／シナリオ法もおすすめです
はじめに「パッケージソフトウェア開発って色んな要素のバランス取りながら仕様決めていくのが難しいんだよね」みたいな話をしておきながら、書いてみるとその辺の話がほとんど出てきませんでした。
何となくゴメンナサイという気持ちです……。
なぜ出てこなかったかというと、
- 目的
- 背景
- 対応項目
- 仕様
あたりの項目は、Design Doc に記載はしたものの、記載内容について考えるプロセスに 直接 Design Doc が寄与していたわけではなかったからだと思います。
目的・背景を考慮しながら対応項目・仕様を考えるにあたっては、ペルソナ／シナリオ法を使いました。
ペルソナ／シナリオ法、これもまたおすすめです！
さすがにここで詳細を説明することはしませんが、この本がとても参考になりました。
- 作者: 川西裕幸,潮田浩,栗山進
- 出版社/メーカー: 日経BP社
- 発売日: 2012/01/26
- メディア: 単行本
- 購入: 5人 クリック: 246回
- この商品を含むブログ (4件) を見る
【UXデザイン入門/川西 裕幸 他】ユーザの調査、ユーザ像の形成から、シナリオ・ストーリーの考案、スケッチを作っては壊す、プロトタイプを（費用対効果を考慮しながら）作る、ユーザビリティテストを行う……... →http://t.co/Cq37mBMnU0 #bookmeter
— Inumerable::LuoYang (@enk_enk) 2014, 8月 27おまけ 2 : MIJS シリコンバレーツアー報告会参加者のブログを見つけました
途中で少しだけ触れた「MIJS シリコンバレーツアー報告会」に、僕と同じように参加して、そこで聞いた Design Doc の話についてブログを書かれている方がいらっしゃいました。
そうそう、そういう感じです。
僕のつたない説明や、もしかしたらリンクしたブログの説明でもピンとこなかった方も、これを見ていただければ Design Doc がどういうものかつかめるかもしれません。
なお、前の方で紹介したブログが直接的には「2009 年頃の Google の Design Doc」について説明しているのに対して、「これはシリコンバレーあたりのスタートアップが今まさに書いている Design Doc」について聞いてきた話をもとに説明しています。
とはいえ、要点は同じと言えそうです。
*1:この辺の話は、会社のブログで2 日めの記事（[パッケージソフトウェア開発Advent Calendar 2014] イマドキパッケージソフトウェアとかどうなのよ問題）にも書いたので、もし興味があればご覧ください！
*2:正確に言うと、ペルソナ／シナリオ法をはじめとして色々なノウハウはあるのですが、「こうしなさい」と決められたやり方はない、という状態です
*3:具体的には、結果としてなんだかんだで 250h 以上（！）の工数を費やすことになりました
*4:ちなみにシリコンバレーツアーというのは、今年の 6 月に MIJS という団体で行われたツアーで、シリコンバレー周辺の企業に訪問したりエンジニアに会ったりしてシリコンバレーの風を感じてくる、みたいなものでした。その際、Design Doc 書いてるよ、という話が出たとのことです。（参考 : MIJSシリコンバレーツアーに参加してきました）
*5:Markdown で書いて、HTML に変換して、課題管理システムに添付、とかしてました……
*6:思わぬ問題が思わぬところから判明したりして、ドキュメントに構っていられなくなってきた
*7:あえて言うなら、課題への添付による間欠的な手動バージョン管理……
*8:Word 2000 あたりのイメージでリッチテキストエディタには多大な不信感がずっとあったのですが、さすがにイマドキのソフトは違います
