2 ms·

This is also what I do. I like UML-ish diagrams to help communicate the ideas with my cow-workers although I use it loosely, not following the formal specs or e

This is also what I do. I like UML-ish diagrams to help communicate the ideas with my cow-workers although I use it loosely, not following the formal specs or even doing it electronically, just on paper, to diagram the interactions and from there design my structures, state transitions, and message sequences. The most serious problem I run into is keeping the documentation synchronized with the project. For everything non-trivial it seems I always get to a point where the project is so far from the docs that it's not worth going back to update. Do you discard the documentation when you've built the thing?

sethammons 8y ago
When I think document driven design, I think more along the lines of "api spec" or giving the interfaces/method signatures. Sometimes this goes into "boxes and arrows" stuff. For boxes and arrows, I usually don't go back and update those. But for the API spec, example usage, etc, I prefer something that is self documenting or has to be kept valid via tests. This is particularly easy in a language like Go (what I tend to work in) as you get GoDoc for free if you comment right, and you can have your examples directory run with tests.