Alec Clews - Creating API documentation for international communities

Alec Clews

Developer Relations Advocate at PaperCut Software International Pty Ltd

Alec's presentation (video recording)

Alec's slides

Q&A

• What tool do you use to make sure that the rules in the style guide are being respected (in the case of API docs and other kinds of docs, like blog posts)?
• Do you test the code snippets as well within your docs? How?
• What are objective indicators in API docs language that shows that they’re written in plain lang? 

How to be objective and not subjective?

”If people don’t understand our API documentation, it’s going to increase support cost because they are going to start asking questions and get frustrated with us. In fact, if they get frustrated enough, they are going to stop using our API… Understanding is greatly impacted by the individual cultural characteristics of people who are consuming the content that we write.”

Why is API Docs Accessibility important?

• Poorly understood API docs can increase support costs and reduce the number of people using your API.
• Understanding is greatly impacted by cultural and individual characteristics.

To fix this problem, write with

• The intention of what you want the customers to get out of your document.
• Empathy, so that as many people as possible can understand it.

Cultural “Markers”

Our behavior and understanding is affected by the culture we are in.

• Culture has dimensions:
  
  • Societal,
  • Individual values and expectations,
  • Organizations have their own culture of doing things.
• Software Development Teams have their own cultural “markers”:
  • Product development approach: A team who does agile development will do things differently than a team who does waterfall development.
  • Relationship with customers: Sometimes they are close, others are distant.
  • Domain of business expertise: Different terminology usage, different way of viewing software development process.
  • Technology choices.

Creating Explanatory Content

”The more accessible you make your documentation, the more easier for global audiences to understand it well.”

• Your technology choices may be unfamiliar to many: supplementary information is important.
• Provide additional material in blogs and knowledge bases: avoid cluttering up your API documentation, provide a way for it to be consumed elsewhere.

Creating API related content

• Use more diagrams to illustrate rightships between things showing sequences of events,API calls, and workflows&processes.
• Diagrams are the ALT tag for to Support the text: they don’t replace it, you still need to provide complete explanations.
• Carefully used videos, images, animated GIFs can enhance documentation (but can be hard to update)
  • Video can illustrate complex procedures.
  • An image highlights pertinent information.

Translation

• It’s hard to translate technical docs: manual translation takes time and is expensive.
• Controlled natural languages can make translation easier:
  • Limited, small vocabulary. Each term and sentence structure are clearly defined.
  • Constrains the text. Makes it easier to understand.
• Machine translation may not be good enough.
• Readers will paste your content into Google Translate anyway.

API Reference Docs

• They need the input of and the review of a technical writer.

• Apply your API Style Guide to reference docs as well:

  • Use descriptive names (functions, parameters and types).
  • Be consistent
  • Provide clear descriptions and summaries.
• Small fragments of inline code (“snippets”) are common to show individual API calls and responses. They support the text but they can’t provide full context.

Provide Complete, Working, Code Solutions

Show me! Don’t Tell me!

Include:

• Useful examples,
• Expectation handling,
• Complex API requests and corresponding responses,
• API set up and tear down as needed,
• Well-written code comments to make it accessible for people who are using different technologies.

Connecting with Your Development Partners

• “Modern Agile”:
  • Deliver content online,
  • Provide frequent updates, continuous iteration and improvement,
  • Engage with online communities e.g., creating Google Groups for addressing questions, sharing knowledge.
• Different dev teams have different needs
  • Stability over frequent changes,
  • Clear signals,
  • Predictable, regular cadence,
  • Formal delivery of assets (e.g., PDF),
  • Passive consumption vs active engagement,
• Try and meet people half way.

Differences in Communication Style

• Some cultures prefer a person to person relationship.
• Development teams (and others) are not familiar with support desk software and processes.
• The 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.