Technical Writing and Documentation 101: Specializations (API Documentation, UX Writing, Developer Relations)

Specializations (API Documentation, UX Writing, Developer Relations)

Specializations in Technical Writing: API Docs, UX Writing, and Developer Relations

A Portfolio-Ready Study Guide for Aspiring & Modernizing Tech Writers

What This Is

Specializations in technical writing allow you to focus on high-impact documentation for specific audiences—developers, end-users, or internal teams. Strong API docs help engineers integrate systems faster (e.g., Stripe’s API reference), UX writing ensures users complete tasks without frustration (e.g., Slack’s empty-state microcopy), and Developer Relations (DevRel) bridges the gap between product teams and the developer community (e.g., Twilio’s tutorials and hackathons). Mastering these areas makes you a strategic asset—not just a "writer," but a product enabler.

Key Terms & Tools

API Documentation

• REST API: A web API that uses HTTP methods (GET, POST, PUT, DELETE) to interact with resources (e.g., /users). Docs must explain endpoints, parameters, responses, and authentication.
• OpenAPI (Swagger): A machine-readable spec (YAML/JSON) that describes REST APIs. Tools like Swagger UI, ReDoc, or Stoplight auto-generate interactive docs from the spec.
• Postman: A tool for testing APIs. Use it to validate endpoints before documenting them. Export collections to share with users.
• cURL: A command-line tool for making HTTP requests. Always include cURL examples in API docs (e.g., curl -X POST https://api.example.com/users -H "Authorization: Bearer token").
• SDK (Software Development Kit): A pre-built library (e.g., Python, JavaScript) that simplifies API integration. Docs should include SDK-specific examples (e.g., stripe.Charge.create()).
• Authentication: How users prove their identity (API keys, OAuth, JWT). Document exactly where to place tokens (headers, query params, body).
• Rate Limiting: Rules on how often an API can be called. Specify limits (e.g., "100 requests/minute") and error codes (e.g., 429 Too Many Requests).
• Webhooks: "Reverse APIs" where the server sends data to a user’s endpoint. Docs must explain payload structure and how to set up a listener.

UX Writing

• Microcopy: Small bits of text that guide users (e.g., button labels, error messages, tooltips). Example: "Your changes are saved automatically" (vs. "Save").
• Voice & Tone: The personality of your writing (e.g., Google’s "friendly but professional," Mailchimp’s "playful but clear"). Define this in a style guide.
• Empty States: Screens shown when no data exists (e.g., "No projects yet. Create one to get started"). Use action-driven language.
• Error Messages: Explain what went wrong and how to fix it (e.g., "Invalid email. Try again or reset your password").
• A/B Testing: Comparing two versions of microcopy to see which performs better (e.g., "Sign up" vs. "Get started").
• Figma/Adobe XD: Design tools where UX writers collaborate with designers. Use plugins like "Content Reel" to manage microcopy.

Developer Relations (DevRel)

• Developer Advocacy: A role focused on educating and engaging developers (e.g., writing tutorials, speaking at conferences, creating sample apps).
• Community Management: Building and nurturing a developer community (e.g., GitHub Discussions, Discord, Stack Overflow).
• Sample Apps: Working code examples that show real-world use cases (e.g., a React app using your API). Host on GitHub with a README.md.
• Hackathons: Events where developers build with your product. Provide starter kits (e.g., pre-configured repos, API keys).
• Feedback Loops: Collecting developer pain points and advocating for improvements (e.g., "Docs are missing WebSocket examples").
• Metrics: Track engagement (e.g., GitHub stars, API call volume, tutorial completion rates).

Step-by-Step / Process Flow

API Documentation Workflow

1. Read the API spec (OpenAPI YAML/JSON) or talk to engineers to understand endpoints, parameters, and responses.
2. Test the API in Postman or cURL. Verify:
3. Required/optional parameters
4. Success/error responses
5. Authentication flow
6. Draft the reference docs in Markdown or a docs-as-code tool (e.g., Sphinx, Docusaurus, MkDocs). Include:
7. Endpoint description
8. Parameters (with data types and examples)
9. Response schema (use JSON Schema for validation)
10. Code examples (cURL, Python, JavaScript)
11. Add conceptual docs (e.g., "How to authenticate," "Pagination guide") and tutorials (e.g., "Build a weather app with our API").
12. Generate interactive docs from OpenAPI using Swagger UI or ReDoc. Embed in your docs site.
13. Submit for review via GitHub PR. Tag engineers for accuracy checks and product managers for clarity.

Example OpenAPI Snippet (YAML):

paths:
  /users:
    get:
      summary: List all users
      parameters:
        - name: limit
          in: query
          schema:
            type: integer
            default: 10
      responses:
        '200':
          description: A list of users
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'

UX Writing Workflow

1. Review the design mockups in Figma/Adobe XD. Identify all text elements (buttons, labels, error messages).
2. Write microcopy following the style guide (e.g., "Use active voice," "Avoid jargon"). Example:
3. ❌ "The system has encountered an error."
4. ✅ "Something went wrong. Try again."
5. Test for clarity with real users (e.g., "Can you complete this task without help?"). Use usability testing tools like UserTesting or Maze.
6. Collaborate with designers to ensure text fits UI constraints (e.g., button width, mobile screens).
7. A/B test variations (e.g., "Sign up" vs. "Create account") using tools like Optimizely or Google Optimize.
8. Document decisions in a content style guide (e.g., "Always use sentence case for buttons").

Developer Relations Workflow

1. Identify the audience (e.g., frontend devs, data scientists). Tailor content to their needs.
2. Create a sample app (e.g., a Python script, React component) that solves a real problem (e.g., "How to process payments with Stripe").
3. Write a tutorial with:
4. Prerequisites (e.g., "You’ll need Python 3.8+")
5. Step-by-step instructions (with screenshots/code snippets)
6. Troubleshooting (e.g., "If you get a 403 error, check your API key")
7. Publish on multiple channels:
8. Blog post (e.g., "Building a Chatbot with Our API")
9. GitHub repo (with a README.md and CONTRIBUTING.md)
10. Video walkthrough (YouTube, Loom)
11. Engage the community:
12. Answer questions on Stack Overflow or GitHub Discussions
13. Host a live Q&A or AMA (Ask Me Anything)
14. Gather feedback and advocate for improvements (e.g., "Developers struggle with OAuth—let’s simplify the docs").

Common Mistakes

API Documentation

UX Writing

Developer Relations

Tech Writing Interview / Portfolio Tips

What Hiring Managers Look For

1. API Docs:
2. Can you read an OpenAPI spec and turn it into clear docs?
3. Do you understand authentication flows (OAuth, API keys)?
4. Can you write code examples in multiple languages (Python, JavaScript, cURL)?

5. Tricky distinction: Reference docs (dry, factual) vs. tutorials (step-by-step, opinionated). Show both in your portfolio.

6. UX Writing:

7. Can you simplify complex ideas into microcopy?
8. Do you have design tool experience (Figma, Adobe XD)?
9. Can you A/B test and iterate based on data?

10. Tricky distinction: Error messages (what went wrong) vs. empty states (what to do next). Include both in samples.

11. Developer Relations:

12. Can you write a tutorial that teaches a concept by building (not just explaining)?
13. Do you have community engagement experience (e.g., GitHub, Stack Overflow, Discord)?
14. Can you create a sample app that solves a real problem?
15. Tricky distinction: DevRel (education + advocacy) vs. developer marketing (promotion). Highlight technical depth in your work.

Portfolio Tips

• API Docs: Include:
• A Swagger UI/ReDoc embed (host on GitHub Pages or Netlify).
• A tutorial (e.g., "Build a weather app with our API").
• A GitHub repo with a sample app (README.md with setup instructions).
• UX Writing: Include:
• Before/after microcopy examples (e.g., error messages, button labels).
• Figma screenshots showing your text in context.
• A style guide (even a short one) for consistency.
• DevRel: Include:
• A blog post or video tutorial (e.g., "How to use WebSockets with our API").
• A sample app repo (with a CONTRIBUTING.md for community contributions).
• Community engagement (e.g., Stack Overflow answers, GitHub issue responses).

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: Use docs-as-code with CI/CD pipelines (e.g., GitHub Actions) to auto-generate docs from OpenAPI specs on every code change. Tag engineers in PRs for accuracy reviews.

3. Why? Manual updates are error-prone; automation ensures docs match the latest API version.

4. A designer asks you to write microcopy for a "Delete Account" button. What do you consider?

5. Answer: Use clear, action-driven language (e.g., "Delete my account") and add a confirmation dialog (e.g., "This cannot be undone. Are you sure?"). Test with users to ensure they understand the consequences.

6. Why? Deletion is irreversible; microcopy must prevent accidental actions.

7. A developer relations lead asks you to create a tutorial for a new API feature. What’s your first step?

8. Answer: Identify the audience (e.g., frontend devs, data scientists) and define the goal (e.g., "Learn how to use WebSockets for real-time updates"). Then, build a sample app that solves a real problem (e.g., a chat app).
9. Why? Tutorials should teach by doing, not just explaining.

Last-Minute Cram Sheet

1. API Docs:
2. ⚠️ OpenAPI 2.0 (Swagger) vs. 3.0+: 3.0+ supports webhooks, better examples, and reusable components.
3. Always include: Endpoint, parameters, responses, code examples (cURL + 2 languages), error codes.
4. Swagger UI vs. ReDoc: Swagger UI is interactive (try endpoints); ReDoc is prettier but read-only.
5. Docs-as-code tools: Docusaurus (React), MkDocs (Python), Sphinx (Python), Hugo (Go).

6. Markdown tip: Use fenced code blocks (```) with language syntax highlighting.

7. UX Writing:

8. ⚠️ Tutorial ≠ How-to guide: A tutorial teaches concepts by building; a how-to solves a specific problem.
9. Microcopy rules: Active voice, present tense, user-centered ("Save changes" vs. "Changes will be saved").
10. Error messages: Explain what went wrong + how to fix it (e.g., "Invalid email. Try again.").

11. Figma tip: Use auto-layout for text containers to avoid overflow issues.

12. Developer Relations:

13. Sample apps: Include a README.md, LICENSE, and CONTRIBUTING.md.
14. Tutorial structure: Prerequisites → Step-by-step → Troubleshooting → Next steps.
15. Community engagement: Answer questions on Stack Overflow, GitHub Discussions, and Discord.

16. Metrics: Track GitHub stars, API call volume, tutorial completion rates.

17. General Tech Writing:

18. Style guides: Google (developer docs), Microsoft (UX writing), Mailchimp (friendly tone).
19. Markdown quirks: Use - for bullet lists (not *), --- for horizontal rules, [text](url) for links.
20. Accessibility: Use descriptive alt text for images, semantic HTML (e.g., <button> not <div>).
21. Git tip: Use git rebase -i to clean up commit history before PRs.