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.
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 based around an imaginary API for hospital management system, as most people are familiar with what a hospital is, and what happens inside.
We have have completed the presentation, bar a few teaks, and we are now developing the course exercises and answers. The slide deck currently runs to 256 slides, which means this will almost certainly be a two day course.
We think this course is probably best suited to being delivered in a classroom. We may also offer it as a live, web-delivered course using webinar software for teams based outside of the UK. We might develop a recorded e-learning course at some point in the future, but it’s not something you’re likely to see for a while.
For more details, see Documentating APIs – training course.
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.
Our next policies and procedures writing course will be held on Monday 11th April.
Discover how to create clear and effective policies and procedures. This course teaches your staff how to write clear and effective policies and procedures, in a straightforward and efficient way.
We’ve just scheduled another of our Advanced technical writing & new trends in technical communication training courses.
“Discover the advanced new writing styles emerging in technical communication by attending Cherryleaf’s popular training course. Don’t get left behind: past clients include technical communicators from Citrix, GE, IBM UK, Lloyds Banking Group, Sage plc, Schlumberger, Tekla and Visa International.”
It will be held on 22nd March, in central London.
Happy New Year!
A quick update on the availability of places on our upcoming courses:
We will be scheduling another policies and procedures classroom course. This is likely to be held in February.
Here are the dates for our next advanced technical writing & new trends course:
- The next public classroom course will be held on 28th January 2016, at our training centre in central London (SW7).
- A live Web course, for delegates based outside the UK, will be held on 6 & 7 January 2016 (2 x 3 hour sessions).
Discover the advanced new writing styles emerging in technical communication by attending Cherryleaf’s popular training course. Don’t get left behind: past clients include technical communicators from Citrix, GE, IBM UK, Lloyds Banking Group, Sage plc, Schlumberger, Tekla and Visa International.
See Advanced technical writing & new trends in technical communication training.
You can now sign up for all of Cherryleaf’s popular online training courses at a discounted price!
This bundle provides you with access to:
By purchasing this bundle, you’ll save £180 ex VAT. That’s a discount of 38%.
See: Cherryleaf training course bundle – all our online courses at a discounted price