経緯
Word, Excelで仕様書を作ることが多いが、結構ストレスがたまる。。。
- 差分が分からない
- プルリクエストが使えない
- 複数人で編集しづらい
そこで軽量マークアップ言語のMarkdown, asciidocで作成し、HTML化することでいろんなメリットがあるので紹介します。
Markdown, asciidocとは？
- wiki形式で記述し、HTMLなどに変換
- 他にもtextile, reStructuredTextなど
- 例(asciidoc)
メリット一覧
変更の差分が簡単に分かる
- Word, Excelで差分を表すときは色を変えるなどの方法があるが面倒＆戻すのも面倒
- Githubなどで管理できるが、差分は分からないので、 ただのファイル置き場
- Wordには「変更履歴の記録」機能があるが、 記録の開始を忘れると悲惨
- Markdown, asciidocはテキスト形式なので、Githubなどで 差分が簡単に確認できる
差分が確実に分かるので、Word, Excelでありがちな、意図しない変更が入ったりすることが無い
Githubのプルリクエストが使えるので、レビューが劇的にラク
- これまではレビュー文書を作り、指摘一覧表を作ってやっていたが、レビューアもレビューイも つらすぎる
- レビュー文書を作るのが面倒
- レビューアは指摘箇所を記載するのが面倒
- レビューイは指摘箇所を探すのが面倒
- Markdown, asciidocはテキスト形式なので、Githubのプルリクエストが使えるので、それらの手間が一切ない
なので、プログラミングと同じプロセスでレビューを回すことができる
複数文書にまたがる検索・置換ができる
- テキスト形式なので、grepを使えば複数文書にまたがる検索や置換が一発できる
- 用語や仕様の変更対応が簡単＆変更漏れが起きない
自動化しやすい
テキストファイルなので、既存サービス・既存ツールと連携しやすい
既存のものがなければ自分で作ればなんとかなる
- 自動化例：
- 表記ゆれの自動指摘（レビューアがつまらない指摘をしなくて済む）
- 「ユーザー」「ユーザ」、「である」「ですます」、全角・半角混在
- プルリクエストを作成し、Reviewersを設定したら自動的にその人にslackでレビュー依頼
- プルリクエストをマージしたら、自動的にslackに通知
- 表記ゆれの自動指摘（レビューアがつまらない指摘をしなくて済む）
複数人で編集しやすい
- Word, Excelは1つのファイルを複数人で編集することができない（Office365を使えば可能だが）
- 規模が大きいシステムの場合、仕様書は何百ページとなり、Word, Excelの1ファイルは現実的ではない。なので、モジュール・章ごとにファイルを分けるが、見る順番が分からない。ファイル名に章番号を入れてソートする手段もあるが、途中で章が増えたら悲惨
- asciidocには複数ファイルを1つにまとめるinclude機能があるので、章ごとにファイルを作っても最終的には1つのHTMLにできる。
他者とのやりとりがストレスフル
仕様を聞かれた場合、
- Word, Excelの場合、いちいちページ番号や章名を手打ちしないといけないのが面倒
- 相手が持っているファイルのバージョンが違う場合、ずれている可能性
- Markdown, asciidocの場合、HTMLなので、リンク先だけを伝えればOK
常に最新、散在しない
- Word, Excelだと他者とはファイルでやりとりするので、
- 最新じゃなく、 仕様書と実際の挙動が違うことがある
- 新旧バージョンのファイルが散在、しかも誰にどのバージョンが渡っているかは不明
- 更新があった時に逐次ファイルを渡すのが面倒
- Markdown, asciidocはHTMLなのでWebサーバーに保管＆参照
- ファイルの受け渡しはしないので散在することがない
- 常に最新のファイルしか表示されないので、仕様書と実際の挙動が違うことが無い
外部向け・内部向けの仕様書でも二重管理にならない
システムによっては、外部に見せたくない内部仕様や内部APIがあったりして、
内部向けの仕様書、外部向けの仕様書を作る場合がある
- Word, Excelの場合、 95%同じ文書でも別ファイルにしないといけない
- ファイルは2重管理となり、同じ修正をそれぞれのファイルにしなければならない＆漏れが発生
- asciidocの場合、if文(ifdef)が使えるので、社内向けのところだけ記載することが可能
- 乱用すると複雑になるので注意
Word, Excelのメリット
ほとんどの人は使ったことがあるので、学習コストが低い、くらい
ただし、Markdown, asciidocを知らなくても、1日あればそこそこ覚えられる
（プログラミング言語を覚えるよりははるかに学習コストは低い）
まとめ
- 差分確認・プルリクエストのレビュー・他者とのやりとりが劇的に改善され、かなりイキイキ
- 大規模なシステムなど、仕様書が多い＆見る人が多い＆更新頻度が高いほど効果が高い
- 新人が配属されたら、OJTでまずはasciidocを学習 → asciidocで機能仕様書を作成させてます
- フォーマットがテキストだと自動化との親和性が高い
- 色々な改善ネタが湧き出てくる → 実践 → さらにイキイキ
- ドキュメント作成も実装と同じプロセスで回すことができる
- プロセスの統一化・単純化
- プルリクエストが使えるので、他チームの仕様書でも簡単な修正なら、修正依頼するより、自分で直してプルリクエストを出すことで、素早く直せる＆相手チームもマージするだけなので、お互いに嬉しい