Amusing observation: writing the doc for an API at the same time I'm designing the API is causing me to change the API to be easier to document. The end result of that process is a much better API.
@balinares Yep, it feels like a variant of the "to design an API, write a client that uses it" approach 
Follow
@LionsPhil I did that and found that it did not go as far as writing documentation does. Because the API is familiar to me and so I myself do the things with the API without problem. But documenting -- *explaining* the API to someone who would not know it -- lets me identify where things are hard to explain, and therefore likely don't make sufficient sense structurally and should be reworked.
