How to create documentation and write code for an international audience, not just the people who speak and think like you. Make your APIs more useful for everyone on the planet. Much of the documentation supplied by both Open Source and Close Souce projects assume the community have a good understanding of the English language and often North American culture as well. This creates barriers for many solution providers, who are the gateway to potentially huge markets for your project. This talk discusses some of the cultural differences, particularly for people from Asia, in using English language API documentation. It suggests some strategies to help diverse audiences understand you APIs and create solutions using them. The talk will cover not only differences in language but also other cultural differences that are often not obvious. For example: Different expectations about publication formats, release processes, levels of support during the development process Meeting and communications styles Software development workflows, processes, and tools Supporting people who are visually impaired will also be briefly discussed. As well as discussing these issues, specific suggestions will be provided to make API docs accessible for as many people as possible. This talk is based on Alec's work with customers in Europe, North America, Middle East, Asia, and Australasia. The last five have been spent as a developer evangelist working with PaperCut partners in China, Japan, Korea, US and Europe.

1. API Documentation for
Diverse Communities
Alec Clews
API The Docs
Oct 2022

2. I am speaking to you from the lands of
the Wurundjeri people of the Kulin
Nation and I wish to acknowledge them
as Traditional Owners.
I would also like to pay my respects to
their Elders, past and present.
+
More information on
Acknowledgement To Country here
Acknowledgement of country

3. ► Old school software nerd
► Works as a developer relations advocate at
PaperCut Software
► Loves technology and coffee
@alecthegeek
alecthegeek alecthegeek
https://www.linkedin.com/in/alecclews/
► Pronouns: He/Him
Who is Alec?

4. Why is API Docs Accessibility Important?
Poorly understood API docs
Increase support costs
Cultural and individual
characteristics affect
UNDERSTANDING
and
Reduce the number of people
using your API

5. We can fix this problem
It’s Easy! Write Docs with:
1. Intention
2. Empathy

6. Culture?

7. Culture has dimensions
Importantly
► Societal
► The individual
► Organisational

8. Cultural "Markers"
► The primary Written and
Spoken language
► "shared patterns of behaviors
and interactions, cognitive
constructs, and affective
understanding.."
Center for Advanced Research on
Language Acquisition,
University of Minnesota

9. Cultural "Markers" in Software Dev Teams
► Product development approach
(processes & maturity)
► Relationship with customers
► Domain of business expertise
► Technology choices

10. NOT JUST REFERENCE MATERIAL. For instance
What is API documentation?
API reference
Introductions and Concepts
Getting Started guides
Task & Story Based Explanations
Troubleshooting guides...
Technical Writing Here!
Sample Code

11. Creating Explanatory Content

12. Use Existing Best Practices
Write Accessible Content
“Accessible writing is good writing. It makes your
content easier for everyone to consume.”
– Blackboard
Write for Global Audiences. See:
► Google developer documentation style guide
► Microsoft Writing Style Guide
► IBM Style Guide ch 8
► Apple Style Guide
https://illlustrations.co/

13. Write Supplementary Material
► Your technology choices may be unfamiliar to many
► Provide additional material in blogs and knowledge bases
► Stops cluttering up API docs with details
► Get additional value from content
● This is one of our most popular posts ⇒

14. Creating API related Content

15. Use More Diagrams
"One Picture is Worth a Thousand
Words"
"One Diagram Illuminates 500
Words"
Useful for:
► System Components, their
Relationships & Deployment
► Sequences of events and API
calls
► Workflows & processes ...
► Diagrams are the ALT tag for to
SUPPORT the text
► Still provide complete
explanations
● & proper ALT tags on all images
► See Docs for Developers An Engineer’s Field
Guide to Technical Writing Ch 6

16. Example: Application Programming Interface
► Contract between two pieces of software a.k.a
specification. Provides information about:
● What can the clients request (1)?
● What will the server do?
● What will the server send back (2)?
● What can go wrong (3)?

17. Other Media
E.g. Videos, images, animated GIFs
Use carefully!
Issues
► Accessibility
► Harder to keep updated
► Hard to translate
But …
Sometimes best because:
► Video can illustrate complex
procedures
► An image highlights pertinent
information

18. Translation
► It's hard to translate technical
docs:
● They change frequently
● Manual translation takes
time and is expensive
► Controlled natural languages
can make translation easier
► Machine Translation may not be
good enough
► Your readers will probably
paste your content into Google
Translate anyway.

19. API reference content

20. API Reference Docs via Spec files
► Network API docs can also be generated from specification files
► Examples
● RESTful — Open API Specification (a.k.a. Swagger)
● gRPC — Protocol Buffers
● GraphQL — schema files
● XML-RPC — Write it by hand

21. API Reference Docs via source code
► Can be generated directly from source code comments and declarations
► Utility varies -- need to work within tool constraints
► Examples
● Go -- Godoc
● Java -- Javadoc
● Python -- Docstrings
● .NET C# -- XML documentation comments

22. API Reference Docs
Apply your API Style Guide to reference docs as well
► Names (functions, parameters and types)
► Consistent use of terms, explanations
► Simple clear descriptions and summaries

23. Inline Code “Snippets”
► Show individual API calls and responses
► Like diagrams, they support the text
► Important
► But often overused
● No Context
● Syntax, but no semantics

24. Provide Complete, Working, Code Solutions
Show me! Don't tell me!
► A concrete way to answer
questions
► Builds confidence with
quickstart
Beware: Dev language is a cultural
choice
Don't expect your audience to
download and run it without
prompting
Include:
► Exception handling
► Complex API requests and
corresponding responses
► API set up and tear down as
needed
► Well written code comments

25. Connecting with Your Development Partners

26. "Modern Agile" API Doc Delivery
► Delivered online
► Frequent and rapid updates
► Continuous iteration and
improvement
► Engaged Online Communities
► Pull vs Push

27. Other dev teams have different needs
► Stability
► Clear signals
► Regular release cadence
► Formal delivery of assets
(e.g. PDF)
► Passive consumption vs active
engagement
Try and meet people half way

28. Differences in Communication Style
► Some cultures prefer person to
person relationship
► Development teams (and
others) are not familiar with
support desk software and
processes
► Fear of being misunderstood
may result in long follow up PDF
attachments (which can be
hard to use and respond to)
► Public forums (e.g. Google
groups) may be blocked

29. Top Tip
PDF Distribution Tool
https://qrdoc.io/
QR Doc is a free service from PaperCut Software that allows you
distribute PDF documents and keep them up to date

30. Further Information

31. Additional Resources
► 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

32. Resources contd:
► Translation, Localization, and Globalization from the Technical
Communication Body of Knowledge
► Testing your Documentation
► Controlled Natural Language Special Interest Group
► Easy English
► User-Friendly Documentations With Simplified Technical English
from Help Authoring Soft

33. Thank
you