“My code improves far more from writing documentation than writing tests. Documentation forces you to approach your APIs symmetrically.”
Open Source and Constraints
Musings from a Southern software developer
Musings from a Southern software developer
“My code improves far more from writing documentation than writing tests. Documentation forces you to approach your APIs symmetrically.”
Zone of Mr. Frosti 
I pretty much agree. But I think it can be better summed up by saying, “Think about what API you’d like to work with if someone else had written it. Further, think about the information you’d like to know before attempting to use the API.”
If you ask yourself these two questions as you’re developing your API, then the API should be much easier to use and the documentation should almost write itself. At the very least, it should lead to inline documentation that can be parsed with Doxygen which will actually be usable by other people (i.e. _not_ the Groovy/Grails documentation).
A project that I think does this well is AFNetworking (https://github.com/AFNetworking/AFNetworking). On the other end, we have libssh2 (http://www.libssh2.org/). Both are great APIs (for the most part), but only one is a joy to use; and it’s not the one with shitty documentation.
LikeLike
Oh, and there’s another article that I really like on this topic — http://mattgemmell.com/2012/05/24/api-design/ . He is using his Objective-C experience for examples, but it applies to anything.
LikeLike