脱Word, Excel仕様書、Markdown, asciidocで書いたHTML仕様書でイキイキ


# 経緯

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

* 差分が分からない
* プルリクエストが使えない
* 複数人で編集しづらい

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

# Markdown, asciidocとは？

* wiki形式で記述し、HTMLなどに変換
  * 他にもtextile, reStructuredTextなど
* 例(asciidoc)

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/10862/2f610564-18db-61dc-3866-5571271e0c49.png)

# メリット一覧

## 変更の差分が簡単に分かる

* Word, Excelで差分を表すときは色を変えるなどの方法があるが面倒＆戻すのも面倒
  * Githubなどで管理できるが、差分は分からないので、 **ただのファイル置き場**
  * Wordには「変更履歴の記録」機能があるが、 **記録の開始を忘れると悲惨**
* Markdown, asciidocはテキスト形式なので、Githubなどで **差分が簡単に確認できる**
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/10862/ebc84f54-b3a5-9570-92f0-78a074370ebf.png)

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

## Githubのプルリクエストが使えるので、レビューが劇的にラク

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

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/10862/dd1f335d-3799-6d4b-6dca-785c50fea2b0.png)

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

## 複数文書にまたがる検索・置換ができる

* テキスト形式なので、**grepを使えば複数文書にまたがる検索や置換が一発できる**
  * 用語や仕様の変更対応が簡単＆変更漏れが起きない

## 自動化しやすい

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

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

## 複数人で編集しやすい

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

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/10862/2a970c70-5d6e-97a6-6117-cd23f0d1c9d7.png)

* asciidocには複数ファイルを1つにまとめる**include機能**があるので、章ごとにファイルを作っても最終的には1つのHTMLにできる。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/10862/10946b75-066d-ad56-3435-92eadb2e4261.png)

## 他者とのやりとりがストレスフル

仕様を聞かれた場合、

* Word, Excelの場合、いちいちページ番号や章名を手打ちしないといけないのが面倒
   * 相手が持っているファイルのバージョンが違う場合、ずれている可能性
* Markdown, asciidocの場合、HTMLなので、**リンク先だけを伝えればOK**

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/10862/82ad971d-f530-ca7c-106f-5494f35f50c3.png)


## 常に最新、散在しない

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

## 外部向け・内部向けの仕様書でも二重管理にならない

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

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

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/10862/8ab0ff63-8a52-c025-4f71-154778c6c72d.png)

## Word, Excelのメリット

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

## まとめ

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