How do Technical Writers document an API?

API documentation is essential for helping users understand and use APIs effectively. However, writing good API documentation can be a challenging task. This chapter will teach you the best practices for writing API documentation, from understanding your audience to researching the API to testing your documentation.

1. Understand the API

Imagine this: You’re handed a mysterious gadget. It’s shiny, looks powerful, but you have no idea what it does. What’s the first thing you’d do? Yep, figure out what it’s for!

APIs are like that gadget—they solve specific problems and serve specific purposes. Your job is to understand what the API does, how it works, and why it’s awesome.

• Ask Questions! What’s the API’s purpose? What problems does it solve? Who uses it?
• Get your hands dirty! Test the API yourself, chat with developers, and dive into any existing documentation (even if it’s messy—this is where you shine!).
• Pro tip: Don’t be afraid to ask “silly” questions. Some of the best documentation starts with, “What the heck does this do?”

2. Know Your Audience

Let’s pause for a moment. You’re not just writing for the sake of writing. You’re creating something that real people—developers, product managers, or analysts—will use. So, let’s figure out who these people are.

• Developers: They want the details. Endpoints, parameters, authentication—give them all the nuts and bolts.
• Product Managers: They’re more interested in the big picture. How will this API improve the product? What are the use cases?
• Business Analysts: They might want a mix—some functionality details, but also how this API solves business problems.

Think of it like planning a speech: Are you talking to a room full of tech wizards or a group of curious business folks? Tailor your tone and content accordingly.

3. Set Goals

Imagine being handed a map with no “X marks the spot.” Frustrating, right? That’s why you need to set clear goals for your documentation.

Ask yourself:

• What should someone be able to do after reading this?
• Should they be able to make their first API call? Understand common errors? Master advanced features?

For example:

• Goal 1: Help users get started with the API in under 10 minutes.
• Goal 2: Reduce support tickets by clearly documenting error messages.

When you know your goals, the documentation practically writes itself (okay, not quite, but it helps a ton).

4. Gather information (The detective work begins)

• Once you’ve identified your audience and documentation objectives, you can start obtaining API data.

  • To obtain important API information, work with Subject Matter Experts (SMEs) and other stakeholders.
  • Ask relevant questions.

5. Plan Your Structure

Think of your documentation like a house. You need a solid foundation and clear rooms where everything belongs. Here’s a tried-and-true structure:

1. Introduction: What’s the API about? Why should users care?
2. Getting Started: How to sign up, get an API key, and make the first request.
3. Authentication: Explain the security basics (e.g., API keys, OAuth).
4. Endpoints and Methods: Break down each endpoint with supported methods (GET, POST, etc.).
5. Examples and Use Cases: Real-world examples that show users how to achieve their goals.
6. Error Handling: Common errors and how to fix them.
7. Best Practices: Tips for using the API effectively.
8. FAQs: Answer the most common questions.

If that seems like a lot, don’t worry! Start simple, then expand as you go.

6. Write Clearly and Concisely (Keep it simple)

Good documentation isn’t about sounding smart—it’s about being understood. Here’s how to do that:

• Use plain language. If you can say something in 10 words instead of 20, do it.
• Avoid jargon. If you must use technical terms, explain them.
• Add examples! A single example can clarify what 10 paragraphs of text can’t.
• Keep your tone consistent. If your introduction is friendly, don’t suddenly turn robotic in the error handling section.

7. Include Code Samples

Want to win the hearts of developers? Give them working code samples. Think of it as giving them a recipe instead of just describing the dish.

• Include samples in multiple programming languages if possible (e.g., Python, JavaScript, Java).
• Test the samples yourself to make sure they work.
• Use comments in the code to explain what’s happening.

8. Test the API (Become the User)

Here’s a secret: Testing the API yourself isn’t just helpful—it’s essential. By putting yourself in the user’s shoes, you’ll catch errors, clarify steps, and build empathy for their experience.

Tools to Try:

• Postman: Great for testing and visualizing API requests.
• Swagger: Handy for interactive API documentation.
• cURL: Perfect for command-line testing.
• Insomnia: A lightweight, user-friendly API testing tool.

Create a simple test plan and run through every scenario. If something feels confusing to you, it’ll definitely confuse your users.

Make a test plan and run extensive tests to validate the API’s functioning.

9. Review and Gather Feedback

Writing is only half the battle—getting feedback is where the magic happens.

• Share your draft with developers, SMEs, or even a small group of external users.
• Ask questions like:
  • “Does this make sense?”
  • “Are the examples helpful?”
  • “What’s missing?”

Be open to constructive criticism. Every bit of feedback makes your documentation stronger.

10. Publish and Maintain

Congrats! You’ve written amazing API documentation. Now, it’s time to share it with the world.

• Choose a platform to host it (e.g., Swagger, Postman, GitHub Pages).
• Update it regularly. APIs evolve, and your documentation should, too.
• Notify users of major changes. A quick email or update log goes a long way.

Keep in mind that proper API documentation is an ongoing process. It should change in tandem with the API and your users’ requirements. Update and improve your documentation on a regular basis to ensure it stays a helpful resource for developers.

Course completed