I've personally found that to write a good API, you need both code that implements the API and code that uses it, and you also need to write the documentation o

I've personally found that to write a good API, you need both code that implements the API and code that uses it, and you also need to write the documentation of that API. The former reveals flaws in the machine interface, and the latter reveals flaws in the human interface, so to speak. For instance, you might find yourself spending a lot of text trying to explain the naming and then realize that the naming is simply bad.