3 ms·
Design documentation should be done on a whiteboard. You have limited space but that forces you to write down what is important and who it doing what. in a few
by bluGill 2y ago
Design documentation should be done on a whiteboard. You have limited space but that forces you to write down what is important and who it doing what. in a few weens it is so different from reality that you don't feel bad about erasing it for whatever is next.
- simonw 2y ago... as long as you then take a photo of that whiteboard, attach a timestamp and put it somewhere people can find it in the future. Otherwise it's not documentation at all, it's lost to the wind.
- bluGill 2y agoChatis the point - it should be lost to the wind. I have never seen design documentation worth reading except in textbooks where it is only used to explain pattens to students.
- simonw 2y agoRight, and my point is that this stuff genuinely matters and is worth recording - but needs to be recorded with a very clear timestamp (hence my preference for comments in a GitHub issue or PR). Otherwise you'll inevitably find yourself re-litigating old decisions because you never recorded WHY you chose one approach over another.
- bluGill 2y agoWhy is important but that is a very different thing from the desing documents I used to have to write, those would not tell you why.