Alec Clews
Papercut
Creating API documentation for international communities
About the talk:
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.
About the author:
Alec is a software geek who currently works as a senior developer advocate at PaperCut Software in Melbourne, Australia. He started writing API docs 2017 with old school UNIX tools (m4, sed, etc.), but has since improved his content productivity with Hugo, Docker, Plantuml, Make, and many other tools old and new. He has been working in IT for over twenty years and can be found online as "alecthegeek".
