I prefer a hybrid approach. A document explaining some common things to do and generally the idea behind why the API is structured that way (shows me you actually thought about it, and makes it more logical to find different parts of it without necessarily looking it up), and then an API spec showing all the parameters.
How does the math work out on that? Both are fairly mature, I don’t believe that either application takes a considerable amount of development effort to maintain. And taking features from Wordpad and putting them into Notepad has a time and effort cost.