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 »

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:  

API documentation design patterns

One of the current developments in technical communication is the development of a common way to present API documentation. At present, there are a number of different design patterns that organisations are using, but, as with many things, there seems to be a desire to establish a de facto standard. One part of this has… Read more »

Adapting to change in technical communication

Technical Authors work in a profession where they must be able to adapt to changes in the technology sector. Often, the changes relate to the outputs they need to create or the authoring tools they use, and most Technical Authors adapt quite easily to the new situations. However, sometimes there are also changes to writing styles or the… Read more »