プログラマの思索

現代は、タスク管理や障害管理だけでなく、仕様書にもExcel脱却が求められている記事があったのでメモ。
ラフなメモ書き。

【参考1】
エクセルで手順書を作るのはきっとやめた方がいい - Qiita

(引用開始)
ある製品のインストール手順書を作ることになり、参考資料として過去の案件で作ったものをもらったのだが、それはエクセルファイルだった。
どういうものだったかを端的に述べると以下の通り。

目次がない
シート名に番号はついていない
各シートにも番号の記載はない
各シートの中身はスクリーンショットの羅列
スクリーンショットについての説明がほぼない
間違った手順のスクリーンショットも混ざっている
操作の結果を確認する手順が漏れているケースがある

この時点で大分げんなりするが、具体的に辛い点をあげる。

1. 全体像が掴めない
2. 順番に確信が持てない
3. コマンドの内容やインストール先のディレクトリもスクリーンショットに埋まっている
4. インストールがうまくいったかの判断材料がない、それを見つけられない
5. 再利用できない
6. 修正したときに差分がわからない
7. レビューするのが困難
(引用終了)

【1-1】一般に、要件定義書、設計書、テスト仕様書などはExcelで書かれている時がほとんどだ。
しかし、Excelのドキュメントは色んな点で弊害が出てくる。

僕の観点では、Excelファイルは構成管理と相性が悪い、という点が最大の弱点ではないか、とずっと思っている。

まず、GitでExcelを管理してもバイナリファイルは差分が分からないので、履歴管理する効果が薄い。
また、GitHubで管理できないと、コードレビューしにくいし、ユーザからのプルリクエストによるフィードバックも受付できない。
つまり、GitHubがもたらしたソーシャルコーディングという手法を適用できず、アジャイルにドキュメントを修正しにくい。

次に、Excelドキュメントは再利用しにくい。
罫線があったり、画像があったり、レイアウトが特殊だったりすると、修正するだけでかなりの手間がかかる。
特に、シートや節を1個追加すると、インデックスや目次が変わってしまうが、じきに誰も保守しなくなる。
すると、Excel設計書の全体イメージが把握できなくなり、ブラックボックスのような仕様書が残るだけ。

結局、共有ファイルサーバーに、いつ修正されたか分からない状態のExcelドキュメントがたくさん散在することになる。

【参考2】
Atom と PlantUML で快適シーケンス図駆動開発ライフ ｜ Developers.IO

(引用開始)
「認識合わせ」という名目でホワイトボードに図を書いて会話することがよくあります。共通言語で会話してあいまいなところを少なくしたら、マネージャーも安心感がありますし、プログラマも自分がやるべきことに集中できますね。

…3日経ちました。あのとき描かれていたホワイトボードの図のとおりに、実装することになりました。認識の齟齬をなくしてくれた貴重な図です。写真に撮りました。どこに保存してたっけ。やっぱり変更したくなったらどうしましょう。またホワイトボードに書き起こす？DRYじゃないですねえ。

そこで、UML図 が登場します。表現したい図を電子データで作成、保存できて、あとで見るときも役に立ちますね。が、しかし、UML図はそれはそれでやや手間がかかるところもあります。作図を助けてくれるツールやサービスはたくさんありますが、

描画ツールを使いたくない
差分管理ができないのが辛い
メンテするのがいやだ。どこにあるかわかりづらくなる
というのが私の感想です。
（中略）
テキストで書けると差分管理できるようになる点が良いです。履歴が残ります。GitHubの機能が使えます。つまり、変更に対して レビューをしてもらえ、コメントをもらえます。 描画ツールでやろうとするとレビュー方法に工夫が必要ですし、もらったコメントの管理が大変です。GitHubの仕組みに乗せてしまうことでそのあたりの課題が一気に解決できます。

シーケンス図は強い
UMLには種々の図がありますが、こと設計～開発段階においては シーケンス図 が強力です。どのようなコンポーネントがあって、それらがどうやりとりするかを視覚的に捉えることができるためです。

シーケンス図というとオブジェクトがあって、そのオブジェクトのメソッドを実行すると他のオブジェクトが生成される…といったような図をイメージするかもしれませんが、「コミュニケーションをとりつつ進める設計段階」ではもっと大きな粒度、データベースや、外部APIといった粒度をオブジェクトにします。クラスやメソッドレベルのやりとりはコードで十分表現可能 である一方、コンポーネント間のやりとりは外部仕様として日本語ベースになっている ことが多く、後者はたとえ厳密だとしても可読性が低いです。シーケンス図はそれを補完するのに役立ちます。次の図は「ニュースの一覧を外部から取得してクライアントに返すAPI」のシーケンス図です。
(引用終了)

【2-1】設計書にUMLのシーケンス図を書きたい時がある。
なぜなら、たとえば、詳細設計書で仕様の意図を伝えたい時、オフショア開発チームにコンポーネント間の処理のイメージを伝えたい時があるから。
そんな場合、シーケンス図でラフに描くことには意義がある。

しかし、お絵描きするUMLモデリングツールで出力した画像ファイルを設計書に載せると、仕様変更のたびに修正が発生してしまう。
設計書のメンテナンスという作業に、保守PJではかなりの工数を費やされている場合が多いのではないか。

ここでも、たとえば、UMLのシーケンス図をplantUMLでテキストで残し、GitHubで管理し、設計レビューで使う、という運用が紹介されている。
UMLで描いた設計の絵はテキストファイルで保持できるなら、GitHubに載せることで、プログラミングの時と同じような効果が得られる。

【2-2】下記の記事では、設計書は全てテキストで書き切る、という方法が紹介されている。

AsciiDoc と PlantUML と mermaid.js で素敵なテキストベース仕様書ライフ

設計書そのものもMarkdownやAsciiDocでテキストで保持しておけば、Jenkinsで定期的にビルドして最新版のドキュメントを出力する、という手法も採用できる。
つまり、設計書もプログラミングと同様に、最近の開発スタイルを適用できるはず。

Redmineに作業内容をチケット起票
→設計書をExcelでなくテキストで作成
→Gitにコミット
→GitHubやGitlabで設計レビュー、再修正してGitにコミット
→Jenkinsで定期的にビルド
→納品時に、タグ付けした版を成果物として納品

「設計書は全てテキストで書き切る」ことにより、設計書も構成管理の配下になり、アジャイル開発の各種プラクティスが適用できるし、その恩恵も受けられる。

また、チケット駆動開発のメリットであるトレーサビリティを設計書の変更管理に利用できるようになる。
そうすれば、システム保守での元々の要件の調査、仕様変更の影響範囲の調査に大いに役立つはず。

【3】ちなみに、Redmineでもmermaidやplantumlのプラグインが提供されている。
RedmineのWikiに、設計概要やノウハウを集約できるので、便利になるはず。

Redmine Mermaid Macro Plugin

Mermaid Macro - Plugins - Redmine

「mermaidプラグインで始める構成図管理」　20171117 redminetokyo13

RedmineでPlantUMLを使う事例: プログラマの思索

Redmine で技術仕様書を書こう | Aiming 開発者ブログ

plantuml - Plugins - Redmine

【4】しかし、仕様書をExcelでなくテキストで全て書いて、ソース管理と同様にGitの構成管理に置くというやり方は、まだ試行錯誤している所だろう。
たくさんの課題がまだ残っているだろうが、いわゆる上流工程でも下流工程と同様に開発プロセスもIT化していくべきだ、という方向性へ進化せざるを得ないと思う。