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

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.