> I would say that documentation-driven development is not really documentation-first: when I do it there's a close feedback between implementation and document

> I would say that documentation-driven development is not really documentation-first: when I do it there's a close feedback between implementation and documentation. I've done it both ways. I've literally written the documentation first (it's the style of doco you read for the standard Python library), and I've designed the API and written the doco afterwards. In either case there is another step: writing the unit tests. All three steps can have a large effect on the design of the API. You focus on getting the internals working correctly when writing the code - the API is just an interface sitting on top. Unit tests make you focus how easy or otherwise it is to use that API, which turns out to be a very different thing. When when you write the doco, you have to explain how the API should be used to someone else. I can't count the number of times I've produced a working tested API, only to discover when I tried to explain how to use it someone else (ie, write the doco), I've found myself twisted in knots. Rather than push through it's easier to rewrite the API in terms that is easier to explain. I've not noticed doing the three things any particular order is always more efficient that any of the other orderings. Sometimes one stage triggers a lot of re-work, sometimes it doesn't. I guess that means I'm not smart enough to focus on all three outcomes at one time.