PaperCut Software prides itself on its core values:
Caring, Honest, Intelligent, and Nimble.
In order to be truly caring we need to make our product technology available to the widest possible audience across the globe. Not everyone uses English as a first language or has access to the latest technologies.
If you are starting to create international content as well, hopefully, some of our suggestions will be useful to you.
Why should you care about accessibility in your developer ecosystem? Well, if developers don’t understand how to use your APIs then they will either ask your support team or even worse stop using your API. In either case, you end up with very miserable stakeholders.
PaperCut MF and PaperCut NG have, from day one, provided tools to allow customers and partners to integrate different products with our software, mostly using [APIs]( https://en.wikipedia.org/wiki/API ). However, as our product matured over the last two decades, the APIs have evolved and our understanding of how people use them has also improved dramatically. When we recently created our new cloud-native platform we had an opportunity to exploit that understanding for our integration partners and be as inclusive as possible. What are some of the principles we applied in our new developer program to improve accessibility?
Note: This post applies to our cloud-native solutions PaperCut Hive and PaperCut Pocket. This post is also very brief! You could write a book about this (probably more than one, in fact), so expect to do further research. I have provided some links at the bottom of this post.
Be Consistent and use widely understood technology
Make it easier for people to consume your documentation and APIs because they are already familiar with the choices made, and can apply knowledge from one area of the API to another.
-
Consistent in using a widely understood API technology.
In our cloud-native platform, we chose to use REST-based APIs for a few reasons.
- REST APIs are popular and well understood
- The [OpenAPI specification]( https://oai.github.io/Documentation/introduction.html ) provides a consistent way to communicate API reference documentation and is designed to work with REST APIs
-
Provide a consistent security mechanism. Once you expose your API endpoints to the outside world, you must make sure that customers’ information is properly protected. PaperCut use Oauth2 to provide customers with direct control over which systems can access their data. Oauth2 has the added benefit of being well understood because of its wide adoption by other API providers.
Write content that makes as few assumptions about the developer as possible
Many developers are not familiar with PaperCut’s products or the problems that our customers are solving with the PaperCut Hive and PaperCut Pocket solutions. Write content that describes the solutions the APIs provide, assuming the developer does not have intimate knowledge of your product.
-
As well as the normal API references, developer documentation should focus on the what and why questions. Providing OpenAPI Specifications only answers some basic “how to” questions. Developers also need to know
- What type of solutions are possible or user problems can be solved
- How to quickly get started
- How PaperCut will support and help them
- How to get help and get support
- What API security we expect and how to use it
- Provide complete working examples to help developers who may not be familiar with the technology or your product. Small code snippets should also be provided in the documentation, but don’t give the full context developers need.
-
Be careful that your content makes as few “cultural” assumptions as possible. Things to be careful of include
- Is the language as clear and easy to understand as possible? Are you using one long word, when three shorter ones would be better?
- Are you using “local” variants of English, or phrases, that assume you grew up in a particular place
- Have you provided a glossary for uncommon or product-specific terms
- Have you made good use of diagrams to support your text descriptions
- Is your text internally consistent (e.g. are technical terms always used the same way)
-
Is the content accessible to as wide an audience as possible?
- Have you provided enough textual descriptions so that people who cannot view images and diagrams can still get the information they need?
- Have you included navigation aid (table of contents, cross-links, judicious use of white space, and so on)
The Technical Writing profession has been dealing with these issues for many decades, please refer to the references below for a lot more detailed advice
Treat APIs as a product feature
- Focus on delivering useful APIs that partners actually need
- Get feedback and involve your partners in the API rollout
- Start on the low-hanging fruit and climb the hill, don’t start at the top of the mountain
Further Reading
- Writing for a global audience Google developer documentation style guide
- Accessible content Google developer documentation style guide
- Make text content readable and understandable W3 Web Content Accessibility Guidelines (WCAG)
- Mozilla Developer network notes on WCAG
- 5 Tips To Improve Technical Writing For An International Audience on LiNUX.COM
- Translation, Localization, and Globalization from the Technical Communication Body of Knowledge
- Testing your Documentation
- Simplified Technical English (ASD-ST100)
- Attempto Project
- Controlled Natural Language Special Interest Group
- Easy English
- User-Friendly Documentations With Simplified Technical English from helpauthoringsoftware.com
