The Event Is Cancelled!


How to Turn Your Weaknesses into Strength and Make Your API Documentation Shine

I will tell how we tried to make our API docs shine but quickly figured out that we can't use most of the modern tools because of the "too custom" technical stack. Then we decided to turn weakness feature and reused the internal JSON configuration to generate correct OpenAPI 3.0 spec. Then we had a little left to do: reuse already set up RST+Sphinx docs generation pipeline, write 3k field descriptions... oh, wait, what?

Yes, that was a huge problem and the amount of work. Still, we crowdsourced it to the development team to improve their business awareness (and to speed up the process) and created field description guidelines, which I will share with the participants.

I will focus on the high-level things you should think in advance before starting to implement API docs based on our "steps on a rake."

My presentation touches two aspects of documentation: first is how to turn your tools and stack weaknesses into benefits, and second is how important it is to teach others to write and "teach them to fish, not just give a fish."