経緯

Word, Excelで仕様書を作ることが多いが、結構ストレスがたまる。。。

そこで軽量マークアップ言語のMarkdown, asciidocで作成し、HTML化することでいろんなメリットがあるので紹介します。

Markdown, asciidocとは？

Word, Excelで差分を表すときは色を変えるなどの方法があるが面倒＆戻すのも面倒
- Githubなどで管理できるが、差分は分からないので、 ただのファイル置き場
- Wordには「変更履歴の記録」機能があるが、 記録の開始を忘れると悲惨
Markdown, asciidocはテキスト形式なので、Githubなどで 差分が簡単に確認できる

差分が確実に分かるので、Word, Excelでありがちな、意図しない変更が入ったりすることが無い

これまではレビュー文書を作り、指摘一覧表を作ってやっていたが、レビューアもレビューイも つらすぎる
- レビュー文書を作るのが面倒
- レビューアは指摘箇所を記載するのが面倒
- レビューイは指摘箇所を探すのが面倒
Markdown, asciidocはテキスト形式なので、Githubのプルリクエストが使えるので、それらの手間が一切ない

なので、プログラミングと同じプロセスでレビューを回すことができる

テキストファイルなので、既存サービス・既存ツールと連携しやすい
既存のものがなければ自分で作ればなんとかなる

自動化例：
- 表記ゆれの自動指摘（レビューアがつまらない指摘をしなくて済む）
  - 「ユーザー」「ユーザ」、「である」「ですます」、全角・半角混在
- プルリクエストを作成し、Reviewersを設定したら自動的にその人にslackでレビュー依頼
- プルリクエストをマージしたら、自動的にslackに通知

Word, Excelは1つのファイルを複数人で編集することができない（Office365を使えば可能だが）
- 規模が大きいシステムの場合、仕様書は何百ページとなり、Word, Excelの1ファイルは現実的ではない。なので、モジュール・章ごとにファイルを分けるが、見る順番が分からない。ファイル名に章番号を入れてソートする手段もあるが、途中で章が増えたら悲惨

仕様を聞かれた場合、

Word, Excelだと他者とはファイルでやりとりするので、
- 最新じゃなく、 仕様書と実際の挙動が違うことがある
- 新旧バージョンのファイルが散在、しかも誰にどのバージョンが渡っているかは不明
- 更新があった時に逐次ファイルを渡すのが面倒
Markdown, asciidocはHTMLなのでWebサーバーに保管＆参照
- ファイルの受け渡しはしないので散在することがない
- 常に最新のファイルしか表示されないので、仕様書と実際の挙動が違うことが無い

システムによっては、外部に見せたくない内部仕様や内部APIがあったりして、
内部向けの仕様書、外部向けの仕様書を作る場合がある

Word, Excelの場合、 95%同じ文書でも別ファイルにしないといけない
- ファイルは2重管理となり、同じ修正をそれぞれのファイルにしなければならない＆漏れが発生
asciidocの場合、if文(ifdef)が使えるので、社内向けのところだけ記載することが可能
- 乱用すると複雑になるので注意

ほとんどの人は使ったことがあるので、学習コストが低い、くらい
ただし、Markdown, asciidocを知らなくても、1日あればそこそこ覚えられる
（プログラミング言語を覚えるよりははるかに学習コストは低い）

差分確認・プルリクエストのレビュー・他者とのやりとりが劇的に改善され、かなりイキイキ
- 大規模なシステムなど、仕様書が多い＆見る人が多い＆更新頻度が高いほど効果が高い
- 新人が配属されたら、OJTでまずはasciidocを学習 → asciidocで機能仕様書を作成させてます
フォーマットがテキストだと自動化との親和性が高い
- 色々な改善ネタが湧き出てくる → 実践 → さらにイキイキ
ドキュメント作成も実装と同じプロセスで回すことができる
- プロセスの統一化・単純化
プルリクエストが使えるので、他チームの仕様書でも簡単な修正なら、修正依頼するより、自分で直してプルリクエストを出すことで、素早く直せる＆相手チームもマージするだけなので、お互いに嬉しい