どのようにドキュメントに残してアップデートしていくか

wikiなりGoogle Docs / Sheet なりにドキュメントを作って要求、要件とかまとめたり設計をまとめていって実装してもらうというのが普段の案件で自分がやることのよくある流れ。

整理している中で確認項目がメールやチャットだったりissueのコメントですすんでいき、その内容をまたwikiなりのドキュメントに追記してアップデートしていくというのが実装の前段階になる。

その後、実装が進んだ時にその仕様書・設計書的なものには開発した内容をどこまで記載するか？というのを考えることがある。

設計時点での漏れや不備はアップデートするのは当然として。

設計書なのだから追記が不要といえば不要ではある気もするが、実装した時の構成的なもの？意図？だったりざっくりロジックみたいなのを、設計時点は大枠までで詳細なところは実装中にすり合わせながら、という時もあったりする。

そういうのは実装中にドキュメントに追記しておけば、後々振り返った時にみてもざっとは状況が把握できるのかなぁ、と。

どこかに概要を書いておくってのは大事だよなー。同意。
パワポ作るとかはないなー、とおもうし、それだとドキュメント作ることが仕事になってる感。
どうしてもわかりにくいなら仕方ないかもしれないけど。。。

もちろん最終的にはコードを読んだ方が早いんだけど、全体を把握する時にコードを読むのは難しいかもしれないし、コードが読めない場合も考えると、ある程度日本語で理解できる内容になった方がいいんだろうなぁ。

コードに書かれたロジックをドキュメントにするのは無駄だと思うので、細かすぎるドキュメント化は時間の無駄で不要。

そもそもテキストベースだと見にくいから図示された感じのがいい、という場合もあるだろうし。

色々難しいなぁと思うところはあるのだけど。

こちらで書かれているとおり、commit log 的なのを見れば解決することもある。

現在進行形の時はそれでもいいかもしれないし、あとからcommit を見直して理解するということもできるかもしれない。
とはいえGitが使えないからー、という場合もありそうだ。

仕様自体にもid的なものが振ってあってそれに関係するものが串刺して見れれば解決するのか？というとそれはちょっと難しそうな気がしないでもないし。

とりあえずドキュメントの大枠はディレクタが作るというのは起点ではあると思うのだけど、チームで追記、アップデートしていくような流れ、文化があった方がいいのかなぁと思ったりしている。

んじゃそうなると追記ルールは？とかそういう問題も出てくるんだろうなー。
そういうのを前向きに議論しながらやっていけるといいんじゃなかろうか、と。

なんとなく普段やってる流れの中で意識せずやってるところがある気はするので、もっとよくする方法がないものか？は考えてやっていかないとだなー。

ドキュメントを書く場所を集約した方がいいのか、状況に応じて変えた方がやりやすいか、とかもありそうではある。

この方法はやったことなかったから今後なんかの案件で試してみよう。

少しずつでもいいからまずはドキュメントに書くという文化にしていきたいところ。