This article talks about writing API documentation for diverse, global, audiences. It builds on existing best practices and looks at content for APIs. There is an implicit assumption that you are writing in English.
Motivation and background
Cultural differences between individuals and teams affect how people understand information. Poorly understood API documentation will increase support costs as people need to ask more questions. Eventually, if people get sufficiently frustrated, they will stop using your platform and move elsewhere. This is not a great outcome….
As a developer relations advocate, working in a modern agile environment at PaperCut Software, I work with development partners worldwide, and accessible API documentation needs to be front and centre in everything the team does. This means being sensitive to the different ways that people consume and communicate highly technical information. I’m sure this applies to everyone else as well.
Culture is not just about language, who you are, or where you lived during your formative years. It’s about the education system and the environment you grew up in; and the spaces in which you live and work. In particular, when people work in teams, they will adopt specific cultural conventions when communicating and working. As a consequence it’s important to realise that documentation will be consumed by a wide range of people with different expectations, practices and skills.
In a software development environment, there are additional cultural aspects to think about. Different teams use specific tools, processes, and development languages. For example, when I work with people using JavaScript, they will struggle to understand content that assumes experience of the .NET C# programming language, because I’m using terminology and practices that are not common in the JavaScript world. This is not just about language syntax, but affects the way that projects are created, built, and deployed. This generates confusion and misunderstanding.
Good quality API documentation must not only consider differences in written language, but also: organisational processes and communication conventions; technology platforms; and learning styles. Additional thought also needs to be given so that your documentation is inclusive and accessible to people with physical or mental differences.
What follows are notes specific to API documentation:
1. Create sufficient, well written, explanatory content
Often, API publishers assume that providing an OpenAPI Specification or API reference material generated from code comments (e.g. from JavaDoc), is sufficient to help partners successfully develop solutions. Maybe a small few fragments of sample code is also considered helpful. (but please refer to the notes below on API reference content and sample code).
It’s true that any documentation is better than none, but our development partners and customers need, and deserve, better. Developers need access to a full range of API documentation that helps them understand:
-
- The concepts you’re talking about and the product they are integrating with
- The types of solutions they can deliver and what they can (or cannot) create
- How to get set-up and working quickly
-
- API Security
- Details of API lifecycle management
- How to get out of trouble when they hit problems
- How to deliver the final API based solution to customers.
Technical writers already have guidelines and skills that we can use to help us create good quality written documentation for international audiences. For example:
- Write in simple structures.
- Don’t use idiomatic or colloquial expressions.
- Avoid shortcuts, symbols, and abbreviations that could easily be spelled out.
Other technical style guides should also be consulted for advice on writing for international audiences. For example: Google developer documentation style guide; Microsoft Writing Style Guide; and the IBM Style Guide ch 8.
2. Use “API centric” diagrams
Simple, easy to understand, diagrams are extremely valuable, they illuminate and clarify textual explanations. People whose first language is not English can find them particularly useful. Diagrams are useful for showing:
- Relationships between internal and external components
- The sequence in which API calls should occur
- The logical flow of various operations or error recovery processing.
Note: diagrams are not a replacement for textual content. You still need complete explanations of this information as not everyone can read diagrams. You should also put well written alt tags on your diagram so that people using screen readers can get the concept even if they cannot see the diagram.
API documentation benefits particularly from UML sequence and component diagrams, Flowcharts (e.g. UML Activity diagrams) can also be useful. Because we have a diverse audience, and many of them will not be familiar with formal notations, and it is highly recommended that a simple subset of UML is used. It’s better that things are easy to understand, rather than correctly follow UML 2 conventions.
Top Tip: Investigate the use of tools such as Plantuml or Mermaid to generate diagrams from text descriptions.
More complete guidelines for technical diagrams can be found in “Docs for Developers An Engineer’s Field Guide to Technical Writing” Ch 6.
3. Be careful with images and videos
It is often common to include graphical media in your documentation e.g. screenshots and videos. For example: When you are talking about fields in an API method, you’ll want to show how that information affects the user interface; If you have a complex setup procedure for your API, then a video can illustrate that quite well.
But not everybody can watch a video, either because they have a vision impairment or corporate IT policy has blocked access to video sharing services. It’s also harder to keep graphical content current. As a consequence “Use figures [or videos] within blocks of text to clarify or complement your information”, not as a replacement for textual explanations. Many of your partners may need to rely solely on the text explanations.
4. Create high Quality Reference API Reference Material
As mentioned previously, API reference documents are usually generated, either from source code comments, or a specification file (for example an OpenAPI specification). Often the reference text is maintained by the developers coding the API. However, it’s important that the same care is taken with this written content as with the longer form explanatory content discussed above, in particular “free form” textual summaries and descriptions.
The method descriptions for external developers need to be much more complete, and written in an accessible style; contrast this with the way that developers will write descriptions for internal methods. Developers can be helped by providing them with a documentation template for method calls or endpoints.
The reference documents should get the same review process as other written content
Ensure the content is programming language neutral. Note: In the case of application binary interface the language choice may be forced by the platform.
The way that API methods and endpoints are documented will vary depending on the technology being used. You should refer to the relevant documentation for details.
5. Provide complete and working code examples.
Sample code is often restricted to small, self contained, examples. These are useful and can be conveniently inserted into the documentation at appropriate points. However where possible complete working examples should be provided. These solve a number of potential problems:
- Allows the developer ensure their local development environment is set up correctly
- Show the developer the complete lifecycle of a solution, and one possible implementation approach
- Examples that were developed from the documentation, instead of internal knowledge of the API platform, help validate the completeness of the content
- Provide a remote support tool to help troubleshoot local problems.
It’s often difficult to decide what language to use when developing examples, it’s impossible to make a choice that works for everyone. In the first instance use that language or framework that will get the example written and working as quickly or easily as possible. It’s often a matter of opinion, but I think the choices include:
- Python: should be understood by a wide audience and provides a highly productive platform to get a solution up and running quickly
- .NET C#: Widely used and understood in the MS Windows community. If you are a macOS user you can now develop .NET examples for your Windows audience. PowerShell is a potential alternative to C#
- JavaScript or TypeScript running on Node.js or in the browser (if appropriate). This has wide appeal.
6. Supporting third party developers
Publishing well written documentation for global developers means that people will contact you for assistance and to ask general questions (e.g. about solution distribution).
This is where differences in organisational culture become most apparent. As a simple example, the developer relations team at PaperCut uses a support ticket based workflow, but many of our partners use email and, after we steer emails into our ticket system, they treat tickets as a general email thread. This requires adjustment on our part.
On a bigger scale some of our larger enterprise partners in Asia are also not used to rapid updates delivered via the public internet. They need notification of content changes (released) and prefer that we deliver PDF based content. We only do this in limited situations that can justify that investment.
How you choose to respond to these situations will depend on your situation and the circumstances of the request. However you should be deliberate in your choices; balance opportunity, risk, and cost. Be sensitive to the reasons why these differences exist.
¹ The IBM Style Guide, Ch 8.
