1. Strive for consistency
Consistency of terminology, style, and organization are hallmarks of all good communication. It should be a principal foundation of your entire API program and the documentation process. To establish proper consistency throughout your documentation, ensure that the writing style and approach are the same throughout your team of writers.
Following industry standards for your documentation, such as OpenAPI, can also help new users orient themselves quickly to a familiar pattern and establish further standardization. Clear navigation options and a consistent style improve discoverability for both features and your docs.
2. Use plain language and a friendly tone
When writing your docs, keep the language plain and approachable, recognizing that jargon, slang, inside jokes, complicated acronyms, and the like have no place in your documentation.
When the subject is complex, that’s when you should make your writing even simpler. It’s important to note that some users may be coming to your product with relatively little formal education. Your writing must be accessible to the full spectrum of possible users, from self-taught developers, non-native English speakers, and developers fresh out of college to experienced pros with little time to get the job done. Make their lives easier by providing documentation that is easy to understand.
Here are a few other things to look out for when striving for an inclusive tone and plain language in your documentation:
- Be alert to discriminatory language.
- Use clear variable names and function names in code samples.
- Never assume.
- Use gender-neutral terms.
- Add alternate text to images.
3. Provide essential information for the non-technical
Using easy-to-understand, real-world examples can help make technical information more easily understandable for non-technical readers. This is where “try it” or mocking capabilities can make your documentation more useful. They can even make your API more compelling to potential customers.
Just remember, the person consuming your documentation won’t necessarily come from a developer background.
4. Take a design-first approach
At Stoplight, we take a design-first approach to all that we do. This means focusing on building APIs for the humans behind them and considering all stakeholders who may interact with, create, or consume the API. This same approach can be applied to designing your documentation. Your API documentation needs to meet users where they are and speak to their needs. It needs to be more than a list of endpoints and methods. When writing your docs, write for every use case. As you draft your docs, the traditional developer, the non-traditional developer, the business counterpart, possible partners, and the end consumer perspectives should all be kept in mind.
5. Get creative with multimedia
If you aim to make your docs more engaging and inclusive, always try to find ways to showcase hands-on guides to implementation. Get creative, highlight use cases from diverse companies and developers, and provide sample apps and technical manuals based on real-world scenarios. Take advantage of multimedia like videos, graphics, or gifs to make your docs more enticing and cater to those who may absorb information more easily in a format other than strictly text.
Write how you would want someone to explain something to you, taking into account the variety of people and backgrounds that may come across your documentation. Empathy for the developer and user is the primary way to work towards a better end-to-end developer and user experience.
You can read more about writing API documentation here.
Teknita has the expert resources to support all your technology initiatives.
We are always happy to hear from you.
Click here to connect with our experts!
0 Comments