Docs as Code

コードのコメント

Codingしながら、コメントが間違っていたら修正されがち

code reviewの中でも、指摘されることが多い

システムが変更されるたびに、仕様書を必ずupdateできるチームは多くない

ただ、しっかりとまとめた資料ではあるので信頼感は高い

解説

新入り向けのレクチャーなど

先輩メンバーがしっかり調べて作るので、正確なことが多い

でも、詳細の情報は抜けていたり、勘違いが含まれていることも結構ある

作業ログ

その作業を行なった瞬間に正しかった情報のみが残っている

作業途中の勘違いも含まれる

試行錯誤の流れが見えるし、当時の様子をキャッチアップするのには最適

正確に残っている作業ログであれば「当時は動いたはずの手順」が見える

でも、情報源として頼るのことはできない

対話

記憶に頼りながら瞬間的に話すので、まちがることが多い

感覚を共有することはできるが、信じて良いものじゃない