4 ms·
A company I was at followed this approach. But of course putting it in writing then meant it had to be shared and approved or "reviewed"(reviewers of course tho
by bern4444 4y ago
A company I was at followed this approach. But of course putting it in writing then meant it had to be shared and approved or "reviewed"(reviewers of course thought they were approvers which was never the case). We called them TDDs (Technical Design Documents) and they were a nightmare.
The docs were often out of date, as the actual engineering would deviate strongly over time (and short periods of time too, like days).
They were incomplete as we wouldn't quite know what was involved until we actually began figuring it out by writing code and building POCs. We also wouldn't know how far we'd want to take some decisions until we had code to then figure out questions about share-ability, extensibility, ownership, etc.
The project would take significantly longer as everyone would first work on the TDD before ever working with code. Then you'd have to corral approvals which involved comments, questions, and a lot of back and forth. This would take days and could stretch out into weeks.
All in all it became a PITA and I wouldn't care to ever continue this practice.
I agree writing helps clarify intent and understanding, for software that writing comes through by writing code. Phrases like measure twice and cut once don't really make sense for software where getting new wood to cut has an effective marginal cost of 0.
Software is completely different from any physical good so these analogies just don't make sense. It's not like a building where once it's built it's impossible or difficult to change. We can forever update, improve, repurpose, and clean up any and all aspects.
Write a README or a TDD once the project is done to capture how it works, the problem being solved, or any gotchas, limitations, or ideas for future development. But this should go at the end. Lean in to software's strength of exceptional flexibility and adaptibility and stop treating it like a physical thing.