[nomercy400]

Regarding api docs, my experiences have steered me to generate-docs-from-code. The problem with writing api docs first and generate code after, is that writing api docs is a 'business' collaboration, which eventually is not done by developers. The code is a 'technical' model of that api contract. The developers are limited by the api-to-code generator and even more importantly, the limitations of the coding language.

As a result, the 'business' comes up with the api contract, discussed and approved by multiple departments and committees, before the 'technical' developers have to show it is impossible to implement with current technology.