- 2021/01/09 追記
- ドキュメントサイトにREST APIのサンプルを追加
先に結論
注意: 実際のプロジェクトでは公開してはダメなはずなので、actions(github workflow)は使わないように。
VuePressを使っていなかった時の難点
Excelの場合
- セルを方眼紙状態にして仕様変更するたびに整形してゲンナリ
- 段落番号も入力していると、挿入行以降を全部編集するハメに
- バージョン管理やルールが徹底していないと、どれが最新かあやふやに
- 複数人が同時に編集してしまうとmergeが大変。
- 印刷レイアウトまで考えると見切れるなんてことがよくある。
- こんな感じで"仕様"とは違うことで労力がかかってしまう。
google spreadsheetの場合
- 複数人で編集できるのはいいけど、承認プロセスが曖昧になって決定なのか推敲なのかがわかりづらい。
補足
誤解のないように書いておくとExcelは素晴らしいツールだと思っています。
ピボットテーブルによる解析やスクリーンショットを交えたbug報告とか
ただ、「"仕様書"としては他の方法がいいでしょ?」という提案です。
本題
- ということでVuePress。
- 他にも静的サイト作成するものはありますが、使いやすさや導入のしやすさという点でVuePressを選びました。
- VuePressが何かは他に素晴らしい記事があるのでココでは触れません。
- VuePressを仕様サイトとして使うという点だけ絞って書きます。
メリット
- markdownで書けるものならなんでも書き残せる。
- 構成図のようにイメージなら 「draw.io」
- ただし、普通に扱うとsvg形式なので差分を見るのは難しいかも
- これはどのイメージ編集も避けられないと思いますが。
- ただし、普通に扱うとsvg形式なので差分を見るのは難しいかも
- UMLなら「PlantUML」で書ける
- 基本設計としてのユースケース、状態を把握するためのシーケンス図など慣れるとドローツールで書くより楽だったりします。
- gitで管理できる = 差分で変更箇所が見やすい。
- ソースと同じリポジトリで管理できる。
- GitHub等のDevOpsを使えばpull requestでレビューできる。
- ソースと乖離があるかなどチェックリスト化しておくとチェック漏れも防げる♪
- ここまでのことが Visual Studio Code 1つでできる♪
- markdownなのでGitHubやGitLabでも見れる。
デメリット
- どんなものでもやっぱり銀の弾丸はない...
- GitHubやGitLabのSaaSでpagesを使うと一般に公開されてしまうので使えない。
- 対策としては
- オンプレ環境にdeployする
- 自分のPC(ローカル)でdeployする
- など
- 自分のPCでdeployする場合、branchによって表示結果が違うので、運用上の注意が必要。
- 対策としては
- 既にswaggerなど別のサイトを使っていたりするといっしょにするのが難しい。
- この場合はVuePressの仕様サイトをポータルにして目次にしてしまうのがよろしいかと。
- 仕様の納品をPDF等で約束されていた時
- ページ(A4とか)の概念が入ってくるので改ページ箇所とか考えると辛い。
- やったことはないですが、Windowsならヘルプファイルにするとか。
- ここは最初から「HTMLで納品します」と言えたら一番の解決策かも。
まとめ
すでにshpinxとか使っていれば差し替えるほどではないと思っています。
けど、「今までExcelを使っていた」とか「Redmineのチケットにしか仕様が残ってないからまとめたい」なんて場合にはおすすめな方法です。
今後
プロジェクトによって仕様として残したいものは違うことケースが多々あると思いますが、
ほとんどプロジェクトで「これは必要」みたいなことをテンプレとしてサンプルサイトに追加していきたいと思っています。