On the other hand, "Documentation Driven Design" is definitely underrated and an excellent way to end up with a very nice API.
> definitely underrated Good documentation is under-rated; not sure about designing via the documentation. > excellent way to end up with a very nice API. My experience suggests otherwise. I've found that both the code and the documentation "write themselves" at different points of development, progressing logically until they hit some snag or question-mark, with each of them effecting the other side in somewhat unex…
The way I do it is first write a draft of the documentation, of how I want the API to look like. Then check if that basic code is possible (which I can predict most of the times based on experience), then write some more docs or methods. When writing a lib I normally already know where I want to use it, so I can put example snippets from how I want to use it as the documentation first and then try to implement those methods.
Examples of libraries I've written mostly this way:
- https://github.com/franciscop/brownies