41 ms·
On the other hand, "Documentation Driven Design" is definitely underrated and an excellent way to end up with a very nice API.
by franciscop 6y ago
On the other hand, "Documentation Driven Design" is definitely underrated and an excellent way to end up with a very nice API.
- goatinaboat 6y agoDocumentation Driven Design Or “literate programming”
- einpoklum 6y ago> 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 unexpected ways - so that working on just one side first is not the right thing to do.
- franciscop 6y agoSure you might not be able to write 100% of the documentation in one go and then the code, but AFAIK that's neither the goal or the intention of DDD, it's more like "document a bit, write a bit, repeat". 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 https://github.com/franciscop/brownies - https://github.com/franciscop/files https://github.com/franciscop/files - https://github.com/franciscop/backblaze https://github.com/franciscop/backblaze