11 ms·
The real question is "How to keep a software design document up-to-date". I have never seen this done in an efficient way. The first version is ok and over time
by vjvjvjvjghv 12d ago
The real question is "How to keep a software design document up-to-date". I have never seen this done in an efficient way. The first version is ok and over time it deviates more and more from reality.
So far my best experience has been to feed the whole thing into AI and get an overview of the project. That together with a few quick bullet points about the overall purpose of the system is pretty workable.
- mtlynch 12d agoI answered this in another comment,[0] and I don't think there's widespread agreement on this, but I think design docs should be a short-term doc that lives until the design implementation is complete. I don't think design docs are the right format for a document that has to evolve alongside the code forever. [0] https://news.ycombinator.com/item?id=49698580 https://news.ycombinator.com/item?id=49698580
- Linux-Fan 12d agoDon't know about efficient, but there is at least two ways which seem to work OK-ish (although not all that efficient, I gahter): * Do regular certifications. Before certification, check if the document is up to date. If not, update it. * Share the documents to answer teammates' questions. Like with a WIKI it may turn out that the important stuff is actually missing/undocumented/outdated. This is then a good opportunity to fix the document.
- vjvjvjvjghv 12d agoI used to work in medical devices where it's all about documentation and even there nobody took the time or had time allocated by management to work on documentation. And most people aren't good at writing so the documents were terrible.