wikiなりGoogle Docs / Sheet なりにドキュメントを作って要求、要件とかまとめたり設計をまとめていって実装してもらうというのが普段の案件で自分がやることのよくある流れ。
整理している中で確認項目がメールやチャットだったりissueのコメントですすんでいき、その内容をまたwikiなりのドキュメントに追記してアップデートしていくというのが実装の前段階になる。
その後、実装が進んだ時にその仕様書・設計書的なものには開発した内容をどこまで記載するか？というのを考えることがある。
設計時点での漏れや不備はアップデートするのは当然として。
設計書なのだから追記が不要といえば不要ではある気もするが、実装した時の構成的なもの？意図？だったりざっくりロジックみたいなのを、設計時点は大枠までで詳細なところは実装中にすり合わせながら、という時もあったりする。
そういうのは実装中にドキュメントに追記しておけば、後々振り返った時にみてもざっとは状況が把握できるのかなぁ、と。
情報共有は文化や人による違いもあるからなー。
例えばエンジニアであればREADMEに概要書いて詳細はコードやコメント読んでね、でも良かったりするけど、そこに「テキストだと見づらい、パワポないの？」みたいな人が入ると一気に話がややこしくなるし。
— Yoshikazu Aoyama (@blauerberg) February 18, 2020
どこかに概要を書いておくってのは大事だよなー。同意。
パワポ作るとかはないなー、とおもうし、それだとドキュメント作ることが仕事になってる感。
どうしてもわかりにくいなら仕方ないかもしれないけど。。。
もちろん最終的にはコードを読んだ方が早いんだけど、全体を把握する時にコードを読むのは難しいかもしれないし、コードが読めない場合も考えると、ある程度日本語で理解できる内容になった方がいいんだろうなぁ。
コードに書かれたロジックをドキュメントにするのは無駄だと思うので、細かすぎるドキュメント化は時間の無駄で不要。
そもそもテキストベースだと見にくいから図示された感じのがいい、という場合もあるだろうし。
色々難しいなぁと思うところはあるのだけど。
issue trackerのログが流れれば「あ、見ときますね」で共有になる素敵な文化もあれば、「細かすぎて分からんのでwordにしてもらえます？」もあるし。
もちろん、world にサマライズしたところで分からないものは分からないのだけど。
— Yoshikazu Aoyama (@blauerberg) February 18, 2020
こちらで書かれているとおり、commit log 的なのを見れば解決することもある。
現在進行形の時はそれでもいいかもしれないし、あとからcommit を見直して理解するということもできるかもしれない。
とはいえGitが使えないからー、という場合もありそうだ。
仕様自体にもid的なものが振ってあってそれに関係するものが串刺して見れれば解決するのか？というとそれはちょっと難しそうな気がしないでもないし。
とりあえずドキュメントの大枠はディレクタが作るというのは起点ではあると思うのだけど、チームで追記、アップデートしていくような流れ、文化があった方がいいのかなぁと思ったりしている。
んじゃそうなると追記ルールは？とかそういう問題も出てくるんだろうなー。
そういうのを前向きに議論しながらやっていけるといいんじゃなかろうか、と。
なんとなく普段やってる流れの中で意識せずやってるところがある気はするので、もっとよくする方法がないものか？は考えてやっていかないとだなー。
ドキュメントを書く場所を集約した方がいいのか、状況に応じて変えた方がやりやすいか、とかもありそうではある。
プロジェクトの議事録を書く時はGoogle Docsを使うが、
・全部一つのファイルに追記していく
・日付を「見出し1」としてマークアップ
・一回の議事録の終わりに改ページを入れる
・議事録の追加は降順
・リンクになる目次を付けることで、検索性にも優れ、共有も、複数人共同追記も楽になります。
— 名村 晋治@サービシンク (@yakumo) February 13, 2020
この方法はやったことなかったから今後なんかの案件で試してみよう。
少しずつでもいいからまずはドキュメントに書くという文化にしていきたいところ。