設計や仕様を Markdown ファイルで書いてgitに入れるか、wikiに入れるか。
最近の webservice だと mdファイル自体はそこそこ読みやすくしてくれる気がしつつ。
mdファイルを開発側だけで触るのであればgit管理でもいいかもしれないけれども。。。
お客さんとかも触るのであれば Dropbox Paper とかオンラインの方に寄せてもいいのかもしれない。
まぁ、これもbitbucket上で編集してもらう、とかでもいいかもだけど、wiki とかの方が楽といえば楽だろうしな。
最近 Backlog の Git を使うようにしたけど、 Backlog 上では編集できないしなぁ。
やっぱりリポジトリは外部サービスの方が使い勝手がいい気もしてくるな。
Git管理しつつ、特定のフォルダのmdファイルの内容については API 経由で wiki を更新するとかもありなのかなぁ。。
管理画面から編集した時が面倒か。。。。
と調べてたらなんか面白そうなものを見つけた。
ドキュメント管理の将来設計 - Qiita
https://qiita.com/tearoom6/items/9518195fcd92bb87b9d0
Git で管理してコミットもしておきつつ、 wiki に投げられるならありかなー。
あとは検索の問題があるか。
Bitbucket だと一応リポジトリ内の検索はできる。コードも一緒に検索されてくるからそれがいいのか悪いのかはありそう。
Dropbox Paper だとフォルダ内検索っぽい機能はないのかな、、、見た感じ。
スマホとかでも見れるとかも判断材料にはなりそう。
仕様を設計書などに書きつつ、それを見ればすべてわかるようにしておく
そこを起点に開発し、テストをする。
開発中に変更が入れば、設計書を変更してそれをプルリク先に作ってチケット起票して依頼するような進め方にすれば、仕様の変更箇所と開発のチケット＆コミットまで結びつけられるんじゃなかろうか？
先にテスト書いて開発する感じや、先に機能単位のプルリク作ってから開発するような。
実装中に常にドキュメント類をアップデートしていけばそういった問題は発生しないのだけど、どうしても後手になってしまって最後に差分が出る、という話になりがち。
コードからドキュメント作るっていう方法もあるけど、それは少し別の話になるかな、、、という気もしつつ。
その場合は内容的にプログラムを解説する解説書に近いものが出来上がる気はしているので。
とはいえ、初めてコード見る人にはあってもいいとおもうので、それはそれとして自動生成できるようにしておくと強い気はする。
バグは仕方ないにしても、仕様変更や修正などはドキュメントのアップデートを忘れないように、アップデート自体も1タスクくらいのつもりでいてもいいのかもしれないなー
Adobe XDデザインスペックの使い方と、開発者と効率的に連携するヒント – Adobe Creative Station
https://blogs.adobe.com/creativestation/web-design-specifications-speeding-design-development-workflow-improving-productivity
やりたいのは結局 XD が考えてる方向と近そうな気はするのだけど。
どこに重きをおくかと、 XD はワイヤ〜デザイン〜フロントエンド、くらいまでは良さそうな気がするのだけど、CMSを使うときにどの情報を使うかを持たせられないのが若干辛いかな、と。
CMSのデータの持ち方自体はビジュアルとかあまり関係ないから別資料になるわけなので、そのデータをどこにどう見せるか？を必要になるのは、HTMLとCMS のテンプレートを作るタイミングになる訳なので、どちらかというとフロント側の設計書に寄せたいところではある。
結局は Markdown じゃなくてもよくて、チーム内でストレスなくわかりやすい形で共有できる何かができてスムーズに開発できればOKってことで。