Not a single mention of the human element, which I will theorize is the main reason.<p>Psychologically, looking at a formal specification is pretty intimidating. How many people do you know who enjoy sitting down with a cup of coffee&#x2F;tea and their favorite time-worn leather-bound copy of RFC7231?<p>Most developers I know love getting something to work. They love the feeling of having mastered something to the point that just reading &quot;GET &#x2F;widgets&quot; is enough for them to go off to curl and implement the rest ad-hoc as they&#x27;re visually inspecting the JSON and occasionally referring back to the docs.<p>Creating formal specs is probably the most efficient way to go in a purely computational sense, but reading specs is hard work and it&#x27;s not especially inviting or rewarding, especially to a class of workers that would much rather jump in, get their hands dirty, and figure it out themselves. It&#x27;s why developers love frameworks&#x2F;APIs that just <i>feel</i> simple and familiar. The low cognitive overhead, and low barrier to entry gets you into a wonderfully endorphin-driven flow that&#x27;s hard to replicate.<p>Formal specifications are great. But they won&#x27;t likely get read by people. And people, not machines, are going to drive your profit as a business offering a shiny API.<p>So should you focus on your formal spec first, or human-readable API documentation? Probably the latter. And good luck convincing the business owners that a spec is a high priority now that you technically have everything covered.