Lessons learnt from developing our API documentation course

We’ve written our new training course on documenting APIs, bar the model answers, and it’s now out for review. We’ve learnt a few lessons, and confirmed a few beliefs, whilst developing the course. We thought we’d share them below: Start with the absolute basics. It’s best to assume little or no knowledge of the subject, and start from… Read more »

New course – Planning, writing and managing an API documentation project

We’ve started work on a new training course about planning, writing and managing an API documentation project. Primarily aimed at REST APIs, this will help you to organise, plan, author and control your API documentation. This course is aimed mostly at people who are not developers, and no programming experience will be required. The exercises are… Read more »

Should we add an API documentation course to our training roadmap?

One of the factors that influences the development of new training courses is, naturally, the potential level of interest in a  particular course. If you have any comments on what you’d like to see in a course on planning and writing API documentation, please email us with your thoughts.

Reflections on last week’s mini-conference on documenting APIs

Last Friday, I attended and presented at the Write The Docs mini-conference on documenting APIs, held at the Government Digital Services (GDS) building in Holborn. My presentation was called “What makes Technical Communicators uneasy about API documentation, and what can we do about it?”, and there were a number of questions and comments regarding some of… Read more »

One to watch – Swagger2markup

Swagger2Markup promises to simplify the generation of REST API documentation by combining auto-generated API documentation produced by Swagger with manually written content. To include the programmatically generated snippets in your documentation, you’d use Asciidoc’s Include macro. The output would look like this: