The Art of API Documentation: Best Practices for Writers

API documentation writing stands apart from technical writing in its unique demands and audience expectations. Unlike typical technical documentation, API documentation necessitates a deep understanding of programming concepts and language to effectively connect with the audience.

In this session, Robert Delwood, Lead API Documentation Programmer-Writer at Walmart Global Tech delved into the best practices essential for crafting clear, concise, and effective API documentation.

Key takeaways

• Creating API documentation is an art, not a science. The documentation must be clear, concise, and tailored to diverse audiences – from junior developers to C-level executives.
• Understand your audience, prioritize clarity, and avoid excessive linking to keep users on the same page.

Write for yourself:

• Understand the topic thoroughly and explain it as if you’re teaching yourself. This ensures clarity in your documentation.
• Push back on unclear code or poor field names to improve clarity. Ensure field names and values are consistent and descriptive.

Read other’s APIs:

• Explore various APIs online to learn from what others have done. Note what works, what doesn’t, and incorporate these insights into your documentation.

Use Examples:

• Examples are crucial in developer documentation. They provide clarity and save time.
• Developers prefer to copy and paste working code rather than retyping it.

Pitfalls to be avoided:

• Use consistent terms for concepts. Don’t mix “API call,” “request,” “fetch,” and “get” interchangeably. Choose one term and stick with it.
• Avoid unnecessary words like “unique” unless it add value.

About the Speaker

Robert Delwood is a programmer, writer, and programmer-writer, which means he straddles the two worlds of software development and technical writing. Robert specializes in developer-to-developer documentation, notably API reference guides. He is in Chicago’s legal community but formerly with NASA’s Johnson Space Center in Houston where he’s had Zoom meetings with people who weren’t even on Earth. With more than 18 years of experience, he recognizes that documentation is easy. Writing great documentation, that’s hard. He encourages others to up their documentation game.