Technical Writing and Documentation 101: Documenting APIs and SDKs (OpenAPI/Swagger, SDK documentation)

Documenting APIs and SDKs (OpenAPI/Swagger, SDK documentation)

Study Guide: Documenting APIs and SDKs (OpenAPI/Swagger, SDK Documentation)

A practical, portfolio-ready guide for aspiring and experienced technical writers

What This Is

API and SDK documentation helps developers integrate software products into their own applications. Well-written docs reduce support tickets, speed up adoption, and improve developer experience. For example, Stripe’s API reference (a payment gateway) includes interactive endpoints, code samples in multiple languages, and error explanations—so developers can process payments without guessing. Similarly, AWS SDK docs provide getting-started guides, API references, and troubleshooting tips to help users deploy cloud services efficiently.

Key Terms & Tools

• OpenAPI (formerly Swagger):
  A machine-readable specification for describing REST APIs. Enables auto-generated docs (Swagger UI, ReDoc), client SDKs, and testing tools. Written in YAML/JSON.
  Tools: Swagger Editor, Swagger UI, Redoc, Stoplight, Postman (for importing OpenAPI specs).

• Docs-as-Code:
  Treating documentation like source code—stored in Git, written in Markdown/AsciiDoc, built with static site generators (e.g., Docusaurus, MkDocs, Hugo), and reviewed via pull requests.
  Example: GitHub’s API docs are open-source and accept community contributions.

• SDK (Software Development Kit):
  A collection of tools, libraries, and docs that help developers use an API in a specific language (e.g., Python, Java, JavaScript).
  Example: The Twilio SDK for Node.js includes pre-built functions for sending SMS messages.

• API Reference:
  A structured, exhaustive list of endpoints, parameters, responses, and error codes. Often auto-generated from OpenAPI specs.
  Example: Stripe API Reference.

• Getting Started Guide:
  A step-by-step tutorial for first-time users, often including authentication, setup, and a "Hello World" example.
  Example: AWS SDK for Python (Boto3) Getting Started.

• Postman/Newman:
  Tools for testing APIs. Postman lets you send requests, inspect responses, and generate code snippets. Newman runs Postman collections in CI/CD pipelines.
  Tip: Export Postman collections to OpenAPI specs for docs.

• DITA (Darwin Information Typing Architecture):
  An XML-based standard for modular, reusable documentation. Used in enterprise API/SDK docs for single-sourcing (e.g., generating PDFs, web docs, and help files from one source).
  Tool: Oxygen XML Editor.

• Static Site Generators (SSGs):
  Tools that convert Markdown/AsciiDoc into HTML websites. Popular for API docs:

• Docusaurus (Facebook, React-based, supports OpenAPI)
• MkDocs (Python, lightweight, plugins for OpenAPI)

• Sphinx (Python, used by Read the Docs)

• Code Samples:
  Snippets in multiple languages (e.g., cURL, Python, JavaScript) that show how to call an API. Should be tested and copy-pasteable.
  Example: bash curl -X POST https://api.example.com/v1/users \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{"name": "Alice"}'

• Authentication Docs:
  Clear instructions for obtaining and using API keys, OAuth tokens, or JWTs. Often the first stumbling block for developers.
  Example: GitHub’s Auth Guide.

• Error Codes & Troubleshooting:
  A list of HTTP status codes (e.g., 404 Not Found, 429 Too Many Requests) with explanations and fixes.
  Example: Twitter API Error Codes.

• Changelog/Release Notes:
  A timeline of API/SDK updates, breaking changes, and new features. Critical for versioned APIs.
  Example: Stripe API Changelog.

Step-by-Step / Process Flow

How to Document an API (From Scratch or Update)

1. Review the API Specification
2. Read the OpenAPI spec (YAML/JSON) or internal API design docs.
3. Identify endpoints, parameters, responses, and authentication methods.

4. Tool tip: Use Swagger Editor to visualize the spec.

5. Test the API Endpoints

6. Use Postman or curl to call each endpoint.
7. Verify responses match the spec (e.g., status codes, data formats).

8. Example: If the spec says GET /users returns a 200 OK, test it and confirm the response body.

9. Draft the API Reference

10. For each endpoint, document:
    • HTTP Method (GET, POST, PUT, DELETE)
    • Path (e.g., /users/{id})
    • Parameters (query, path, header, body)
    • Responses (status codes, example payloads)
    • Error codes (e.g., 401 Unauthorized)

11. Tool tip: Use Redoc or Swagger UI to auto-generate docs from OpenAPI.

12. Write Code Samples

13. Provide snippets in 2–3 languages (e.g., cURL, Python, JavaScript).
14. Test each snippet to ensure it works.

15. Example:
    python
import requests
response = requests.get("https://api.example.com/v1/users", headers={"Authorization": "Bearer YOUR_TOKEN"})
print(response.json())

16. Add Authentication Docs

17. Explain how to get an API key, OAuth token, or JWT.
18. Include screenshots of the developer portal (if applicable).

19. Example: "To authenticate, include your API key in the Authorization header: Authorization: Bearer YOUR_API_KEY."

20. Create a Getting Started Guide

21. Write a step-by-step tutorial (e.g., "How to Create Your First User").
22. Include prerequisites (e.g., "You need Python 3.8+ installed").

23. Example:

    
    
    1. Install the SDK: pip install example-sdk
    2. Authenticate: client = ExampleClient(api_key="YOUR_KEY")
    3. Make your first call: user = client.create_user(name="Alice")

24. Submit for Developer Review

25. Open a PR in GitHub/GitLab for engineers to review.
26. Address feedback (e.g., "This endpoint is deprecated" or "The response schema changed").

27. Tool tip: Use GitHub Actions to auto-deploy docs on merge.

28. Publish and Monitor

29. Deploy docs to a static site (e.g., Netlify, Vercel, Read the Docs).
30. Set up analytics (e.g., Google Analytics, Plausible) to track popular pages.
31. Example: If POST /users gets 10x more traffic than GET /users, consider expanding its docs.

Common Mistakes

Tech Writing Interview / Portfolio Tips

What Hiring Managers Look For

1. Can you write for developers?
2. Show examples of API references, SDK docs, or tutorials in your portfolio.

3. Tricky distinction: A tutorial teaches concepts by building (e.g., "Build a Weather App with Our API"), while a how-to guide solves a specific problem (e.g., "How to Handle Rate Limits").

4. Do you understand OpenAPI/Swagger?

5. Be ready to explain:

   
   
   • The difference between Swagger UI (interactive docs) and ReDoc (static, prettier docs).
   • How to validate an OpenAPI spec (e.g., using swagger-cli validate).
   • How to auto-generate docs from a spec (e.g., redoc-cli bundle openapi.yaml).

6. Can you work with engineers?

7. Mention tools like Postman, Git, and CI/CD pipelines (e.g., "I set up GitHub Actions to auto-deploy docs on merge").

8. Example question: "How would you handle a situation where the API spec changes but the docs PR hasn’t been reviewed?"

9. Do you know docs-as-code?

10. Show experience with:
    • Markdown/AsciiDoc (e.g., "I wrote docs in Markdown and built them with Docusaurus").
    • Static site generators (e.g., "I migrated docs from WordPress to MkDocs").
    • Git workflows (e.g., "I reviewed docs PRs and used GitHub Issues for tracking").

Portfolio Tips

• Include a real API/SDK doc project (even if it’s a mock API).
  Example: Document a public API (e.g., JSONPlaceholder) using OpenAPI and Docusaurus.
• Show before/after examples of improving docs (e.g., "I rewrote this confusing endpoint description").
• Add a README explaining your process (e.g., "I used Postman to test endpoints, then auto-generated docs with Redoc").

Quick Check Questions

1. A developer complains that the API docs are outdated. How would you ensure docs stay in sync with code?
2. Answer: Implement CI/CD for docs (e.g., auto-deploy on merge) and validate OpenAPI specs in the build pipeline.

3. Why: Prevents drift between code and docs.

4. You’re documenting an SDK for Python and Java. How do you structure the docs to avoid duplication?

5. Answer: Use modular docs (e.g., a shared "Concepts" section) and language-specific tabs for code samples.

6. Why: Reduces maintenance and improves readability.

7. A PM asks you to add a new endpoint to the API reference. What’s your first step?

8. Answer: Test the endpoint in Postman/curl to verify its behavior before documenting.
9. Why: Ensures accuracy and catches undocumented behaviors.

Last-Minute Cram Sheet

1. OpenAPI 3.0 vs 2.0: 3.0 supports callbacks, links, and better examples. ⚠️ Always use 3.0+ for new projects.
2. Swagger UI vs ReDoc: Swagger UI is interactive (try endpoints live); ReDoc is prettier but static.
3. Markdown tip: Use fenced code blocks () with language tags (python) for syntax highlighting.
4. Docs-as-code tools: Docusaurus (React), MkDocs (Python), Hugo (Go).
5. Authentication docs: Always include how to get a key and where to put it (header, query param, etc.).
6. Error codes: Document all possible HTTP status codes (not just 200 OK).
7. Code samples: Test in a clean environment (e.g., Docker container) to avoid "works on my machine" issues.
8. Tutorial vs how-to: Tutorial = build something; how-to = solve a problem. ⚠️ Don’t mix them.
9. OpenAPI validation: Use swagger-cli validate openapi.yaml to catch errors.
10. Git tip: Use git blame to find who last edited a doc (useful for reviews).