I agree with the argument: developers like reading web pages that describe how to use API, covering rationale of API design, gotchas, code samples.<p>However, what if the specs were able to capture what is in such human-readable pages (for example <a href="https:&#x2F;&#x2F;docs.cloudant.com&#x2F;" rel="nofollow">https:&#x2F;&#x2F;docs.cloudant.com&#x2F;</a>)? What if API spec could be automatically derived out of HTML pages? Embed some metadata in HTML page and then we have both cake (human-readable) and eat it (machine-readable)?