運営サイトの仕様書の残し方
ウェブ開発、Webサービス運営に携わっている方々にお聞きしたいです
ある程度長く開発しているウェブサイトやサービスの仕様書を、ウェブに携わる方々はどのように保守保存しているのでしょうか？
規模の大きいサイトになってくると
- この機能はどうしたらフラグが立つんだっけ？
- この部分は件数が0件だったらどういう挙動になるんだっけ？
- このボタン押せないんだけどどうしたら押せるようになるんだっけ？
- 昔ここに他のボタン設置してなかったっけ？
など、コードやgit履歴を追えば確認できるが、非エンジニアではすぐに情報が得られないことを確認したい場面が増えてきて困っています。
現在私が携わっている組織では機能改修などは
google documentやgoogle spreadsheetで要件を書き起こしてコミュニケーションをとっています。
これだと
A→B、B→C
というその時ごとの仕様の変化こそドキュメントが残りますが
A+B+Cとなった最終系の現在の仕様についてはドキュメントが残りません。
カスタマーサポートなどで最終的な現在の仕様を確認する必要がある場合はエンジニアがコードを確認するか、改修時に作成されてきた各ドキュメントを一通り確認するという手法を取らざるを得ない状況です。
- A. 上記と同じ状況
- B. google documentやgoogle spreadsheetで最終的な現仕様ドキュメントも保守管理している
- C. notionやkibelaなどドキュメントツールで最終的な現仕様ドキュメントを保守管理している
- D. figmaなどのデザインツールで最終的な現仕様ドキュメントを保守管理している
- E. コードこそ正義だ、仕様書などいらん
- F. その他
などウェブ開発、Webサービス運営に携わっている方々の知見や知恵をお聞かせいただけると幸いです。
wordpress等を検討したのですがデザインに凝りすぎて手に負えないと思い、dokuwikiをインストールしてナレッジを書き留めています。最初はプラグインの競合に悩まされますが、快適な編集作業が可能です。特に、マウス操作を最小にした編集機能は心地よいです。
markdownのプラグインを入れたのですが、最近はdokuwiki書式でカキコしてます。
特に、画像を貼り付けるプラグインが感動です。今までペイントやエクセルの作業が馬鹿らしく思えます。
尚、コードブロックはスタイルシートで背景をblackにしないとqiitaのような表現になりません。
バックアップはawsのリージョン間でvpn経由でrsyncで同期を取っています。快適です。
私が東京でそこそこ(自身比)な規模のシステムを開発していた時の話になりますが、「外部設計書」、「基本設計書」、「内部設計書」などなど、最新版のドキュメントをSVNで管理する体制になっていました。(CとFの混合のような形式でしょうか)
補足です(蛇足かもしれません)が、
3点述べさせてください。
①開発フローについて
A→B、B→C
というその時ごとの仕様の変化こそドキュメントが残りますが
A+B+Cとなった最終系の現在の仕様についてはドキュメントが残りません。
・A => C に直結するはずなので「A + B + C」が発生する時点で問題が
あるかと思われます。(Gitのfast-forwardのように)
※ドキュメントが残らない事自体も問題かと思われます。
・Gitのフローのようですが
A => B1 と A => B2と分岐があって最終的に
A => B1 + B2 => C となるのであればまた違う運用も想定できるのですが…
②保守について
カスタマーサポートなどで最終的な現在の仕様を確認する必要がある場合はエンジニアがコードを確認するか、改修時に作成されてきた各ドキュメントを一通り確認するという手法を取らざるを得ない状況です。
・こちらについては、運用形態の話とは別ですが
万が一「実装 = 最終的な仕様」になっていない可能性を考慮して
「仕様書に記述されている動作」、「実際の動作」、「コードの内容」を確認するべきかと思います。(許可されている稼働時間の範囲で)
③その他
※重箱の隅をつつくような内容で大変恐縮です。
・「c. notion」に接頭辞の表記ゆれがあります。(想定：大文字統一)
・質問文の「終的な現仕様ドキュメントも保守管理している」が
重複しているのでB・C・Dで共通化して分けるといいかもしれません。
・「E. コードこそ正義だ、仕様書などいらん」論外ですね…
・A => C に直結するはずなので「A + B + C」が発生する時点で問題が
あるかと思われます。(Gitのfast-forwardのように)
※ドキュメントが残らない事自体も問題かと思われます。
おっしゃる通りでございます。
この問題を改善する方法を模索したく、質問投稿させていただいた次第でした。
「外部設計書」、「基本設計書」、「内部設計書」などなど、
最新版のドキュメントをSVNで管理する体制になっていました。
(CとFの混合のような形式でしょうか)
実例を提示いただけて大変参考になります。
うちでも類似の手法が取れないか検討してみます。
私の拙い文章まで丁寧に添削いただき大変ありがとうございます！