I’ve been working with APIs for the past seven years, and the documentation process has been consistently the most painful. Nobody wants to have to do it, it’s filled with gruntwork and repetition, and takes a ton of time. Developers are not technical writers and documenting is never their priority, let alone making docs look nice. But for the reader—often the very same developers, when they’re consuming others’ work—it makes such a difference. How many times have you just looked at the API doc and decided “nope not going to integrate”? That was the case for me and my team many times. Developer communities often complain that even the most well-known companies’ public API docs are incomprehensible, and internal API docs are neglected even more.
The gruntwork and repetition are clues that there’s room for software to do a lot of this work, and particularly for ML models to help produce the content.
We want to allow anyone to create great docs without having a whole team of writers and designers, so we researched what makes Stripe, Square, and a few other API docs so great. First, it was definitely the content. Second, it was the user-friendly interface: layout, colors, scrolls, how easy it was to find information and give feedback. We talked to developers and technical writers to understand their pain points. Then we took all that research along with Maria’s experience as an ML Engineer at Microsoft, Deepmind, Google, and Facebook to come up with Theneo, a Technical Writer AI Assistant.
Theneo is like having a technical writer next to you. You upload your API collection (JSON, YAML, etc.). Our models automatically load and analyze API requests, methods, endpoints, request body, parameters, etc., then run some quality checks (e.g. for grammar errors) and give you content suggestions for the section names and descriptions.
API docs generated by Theneo are user-friendly, beautiful and interactive. we automatically generate all of your API requests in multiple languages and make it interactive for the reader. Here is an example: https://app.theneo.io/demo/theneo
For internal API docs, we created several integrations that make it easy to create and maintain API documentation: Postman Integration - you can pull all of your collections and use them in Theneo; Github Actions - you can define how and when you want API docs to be updated automatically (https://github.com/marketplace/actions/theneo-api-documentat... Visual Studio Code (coming soon) - by the end of this month you will be able to create and preview your API documentation right in your IDE. We do not use your private API docs for ML training.
You can see a quick overview of how our setup works here: https://www.loom.com/share/792fc6008a914d068ff8b34994fbc467
We are coming up with a lot of new integrations and features to make it easy for developers to generate and maintain internal or public-facing API docs. We would love to hear from you, what you are currently using, what you love or don’t love about those solutions, what stops you from having high-quality docs for your APIs, and anything else you’d like to share!
by Andrey
Azimov