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 there. It’s easier to skip or omit those sections, than try to add them in at a later stage.
  • Stick with a single theme for the exercises and examples. One of the challenges we had was to create exercises and examples that take delegates through all the stages of developing API documentation. We decided to base these on an imaginary API for a hospital, and this turned out to be a good choice. It’s meant we can use real world examples from healthcare,  as well as ones we’ve created, during the course.
  • Make the examples visceral. The more you can anchor the exercises into people’s lives and experiences, the more real and meaningful they will be for them.
  • Don’t get sucked into looking at only one tool. There are a number of ways to develop API documentation, and the tools are developing at a rapid pace.
  • Don’t be too ambitious with the exercises.
  • Writers want to write on a training course about documentation, so give them the opportunity to do so.
  • Set realistic expectations regarding coding skills. You can’t teach people how to code in multiple languages in a day, so you need to provide building blocks that they can build upon in the future.

The slide deck now comprises 330 slides, and the test recordings indicate it’s a one day course. We’re still not convinced we have the best title for the course – if you have any suggestions, do let us know.

Leave a Reply

This site uses Akismet to reduce spam. Learn how your comment data is processed.