> such design choices belong in a more detailed technical design document I agree with you but in my experience unless you are writing this documentation in a

> such design choices belong in a more detailed technical design document I agree with you but in my experience unless you are writing this documentation in a regulated industry (with external incentives to keep the documentation up to date) the technical docs will eventually go stale or out-of-sync with the actual implementation.