Technical writing with Continuous Integration and docs-as-code
For both OpenStack and Rackspace cloud APIs, we use WADL, Web Application Description Language, to build an API reference listing for all REST API calls. In a previous post, I discussed how the reference pages at http://developer.openstack.org/api-ref.html were made with a WADL source and a Maven plugin, clouddocs-maven-plugin. (Updated to add: in 2023, you would use OpenAPI Specification […]
I know a lot of people who want to consume awesome API docs. Let’s talk about what it takes to get started writing them. I’m not talking about completing your API docs. I’m talking about just getting started, what does it take? For API documentation especially REST APIs, I’d advocate a reference-first approach. Like the […]
Rip. Shred. Tear. Let’s gather up the obstacles to documentation contribution and tear them down one by one. I’ve designed a survey with the help of the OpenStack docs team to determine blockers for docs contributions. If you’ve contributed to OpenStack, please fill it out here: https://docs.google.com/forms/d/136-BssH-OxjVo8vNoOD-gW4x8fDFpvixbgCfeV1w_do/viewform I want to use this survey to avoid […]