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 the slides that I felt I should expand on.
1. Are there really so few people with API documentation experience?
I showed the results from searching on LinkedIn for Technical Authors in the UK who have API in their profile, to give a rough indication of the number of people with API documentation writing skills and experience. It’s hard to provide accurate figures because:
- People writing API documentation are not always called Technical Authors.
- There’s no Standard Industrial Classification (SIC) code in the UK for Technical Authors, which means there aren’t any official statistics.
- There are approximately 30 million working people in the UK, and only 19 million of them are on LinkedIn.
However, even if we double the number found in the search results, it’s still a very small pool of suitably qualified people.
2. The difference in the skills required for Technical Authors and API Documentation writers.
A lot of people photographed the slide describing the differences in skills required. In the presentation, I pointed out that the priority of the skills could change, depending on circumstances. It’s not in a fixed order.
The main difference is that API documentation requires a much higher level of knowledge about the subject matter. To create an end user guide for an accountancy package, where you are describing mostly tasks, you don’t necessarily need to know a great deal about accountancy. To create an API guide, where you are describing mostly facts, you need to have a greater understanding of the subject matter.
3. The differences in the readers.
I said that Technical Authors tend to describe technical information to a non-technical audience, whereas API documentation writers tend to describe technical information to a technical audience. Some people challenged this statement. I should have said that Technical Authors tend to describe technical information to a non-technical and a technical audience. I believe it’s true to say that the readers of API documentation are more competent technically, and so there will less explanation of basic concepts in API guides.
The event was excellent, with many very interesting speakers. The GDS is working on developing a design pattern for Gov.uk APIs – for example, for the Local Waste Service Standards Project and for the Companies House API. It’s clearly early days for the GDS, but I suspect, where Gov.uk leads, others will follow.
Leave a Reply