[florianmartens]

This article is awesome and resonates with my experience! I used to work for one of the big cloud vendors. We frequently had doc writers in our sync calls. Quite frankly, they never had a chance! Much of our documentation, our errors, status codes etc. was burried in the code and we (developers) were simply to busy to work effectively with technical writers.

Don't get me wrong here. Where I say "busy" I don't mean their work wasn't important (it was!) but we had our own projects and jumping on a call to improve errors messages is not too exciting for most of us - and it's not the stuff that drives promotions. As a develper it's simply to easy to gatekeep code.

Now follows a shameless plug: I'd be so excited to hear your opinion about a tool I'm building. It's called https://api-fiddle.com. Conceptually, it should help developers work API-first instead of code-first. It's great for devs because it makes the work faster and safer. BUT, an added benefit is that API docs are no longer burried in code and technical writers have a nice interface to contribute to them (and hold devs accountable!).