Technical Writing
Random

Click random to get a fresh chapter.

Technical Writing and Documentation 101: Developer Portal Design and Information Architecture

Developer Portal Design and Information Architecture

Developer Portal Design & Information Architecture: A Practical Study Guide

For aspiring technical writers, developer-to-writer transitions, and writers modernizing their skills

What This Is

A developer portal is the central hub where developers find everything they need to integrate with your product—API references, SDKs, tutorials, authentication guides, and troubleshooting docs. Think of it like a "control center" for developers: if it’s well-organized, they’ll adopt your product faster; if it’s confusing, they’ll abandon it.

Real-world example:
Stripe’s API documentation is a gold standard. It combines: - A reference (auto-generated from OpenAPI) with interactive code samples.
- Guides (e.g., "Accept a payment") that walk through workflows.
- A sandbox for testing API calls without real transactions.
- Changelogs and status pages to keep users informed.

A poorly designed portal (e.g., buried docs, no search, outdated examples) forces developers to dig through forums or contact support—costing your company time and trust.

Key Terms & Tools

• Information Architecture (IA): The structure and labeling of content so users can find what they need. In dev portals, this means grouping docs by user journey (e.g., "Get Started" → "Build" → "Deploy") rather than by product feature.

• Tools: Card sorting (Optimal Workshop), tree testing (Treejack), sitemap generators (Dynomapper).

• Docs-as-Code: Treating documentation like software—stored in Git, written in Markdown/AsciiDoc, built with static site generators (SSGs), and reviewed via pull requests.

• Tools: GitHub/GitLab, Markdown/AsciiDoc, SSGs (Docusaurus, MkDocs, Hugo), CI/CD (GitHub Actions, Netlify).

• OpenAPI (formerly Swagger): A machine-readable spec for REST APIs. Lets you auto-generate docs, SDKs, and interactive API explorers.

• Tools: Swagger UI, ReDoc, Stoplight, Postman (for testing).

• Static Site Generator (SSG): A tool that builds a website from Markdown files (e.g., Docusaurus, MkDocs). Faster and more secure than CMS-based docs.

• Example: Stripe’s docs use a custom SSG; Twilio uses Docusaurus.

• API Reference: The "dictionary" of your API—endpoints, parameters, responses, and code examples. Usually auto-generated from OpenAPI.

• Tools: Swagger UI, ReDoc, Slate, Redocly.

• Tutorial vs. Guide vs. Reference:

• Tutorial: Step-by-step learning (e.g., "Build a weather app with our API").
• Guide (How-To): Solves a specific problem (e.g., "Handle webhook signatures").

• Reference: Factual details (e.g., "GET /users endpoint").

• Developer Experience (DX): How easy and pleasant it is for developers to use your product. Good DX = clear docs, working examples, and minimal friction.

• Example: Twilio’s Quickstart lets you send an SMS in 5 minutes.

• Interactive API Explorer: A tool that lets users test API calls directly in the docs (e.g., Swagger UI, Postman embedded).

• Tools: Swagger UI, Postman Public API Network, ReadMe.

• Changelog: A timeline of updates (new features, breaking changes, deprecations). Critical for transparency.

• Tools: Keep a Changelog (format), GitHub Releases, or a dedicated page (e.g., Stripe’s changelog).

• Authentication Docs: Clear instructions for API keys, OAuth, JWT, etc. Often the #1 source of support tickets if poorly written.

• Example: Auth0’s docs separate "Quickstart" from "Concepts" to avoid overwhelming users.

• Search & Navigation: Devs expect Google-like search and intuitive menus. Poor search = frustrated users.

• Tools: Algolia (used by Stripe, Twilio), Lunr.js (lightweight), or built-in SSG search (Docusaurus).

• Feedback Loops: Ways for users to report issues or suggest improvements (e.g., "Was this helpful?" buttons, GitHub issues, or Slack communities).

• Example: GitHub’s docs include a "Give feedback" button on every page.

Step-by-Step: Designing a Developer Portal

Follow this process to build or improve a dev portal:

1. Audit Your Users & Their Goals

• Action: Interview developers (internal or external) to answer:
• Who are they? (e.g., frontend devs, backend engineers, hobbyists)
• What are their top 3 tasks? (e.g., "Integrate payments," "Debug webhooks")
• What’s blocking them? (e.g., "Can’t find the OAuth docs")
• Output: A list of user personas and jobs to be done (JTBD).
• Example: For a payment API, personas might be:
  • Novice dev: Needs a tutorial ("Build your first checkout").
  • Enterprise dev: Needs reference docs ("Webhook signature validation").

2. Map the Information Architecture (IA)

• Action: Group content by user journey, not product features. Use card sorting or tree testing.
• Example IA for a cloud API:
  ```
  1. Get Started
  2. Quickstart
  3. Authentication
  4. Build
  5. Tutorials (e.g., "Deploy a serverless function")
  6. Guides (e.g., "Handle rate limits")
  7. Reference
  8. API Reference (auto-generated from OpenAPI)
  9. SDKs (Python, Node.js, etc.)
  10. Deploy & Monitor
  11. Logging
  12. Error codes
  13. Support
  14. Changelog
  15. Status page
  16. Community forum ```
• Tool: Use Optimal Workshop for card sorting.

3. Choose Your Tech Stack

• Action: Pick tools based on your team’s skills and needs:
• Docs-as-Code: GitHub + Markdown + Docusaurus/MkDocs.
• API Reference: OpenAPI + Swagger UI/ReDoc.
• Search: Algolia (for large portals) or Lunr.js (for small sites).
• Feedback: GitHub issues or a "Was this helpful?" button.
• Example Stack:
  | Component | Tool | Why? | |--------------------|--------------------|---------------------------------------| | Content | Markdown | Easy to write, version-controlled. | | Site Generator | Docusaurus | React-based, great for API docs. | | API Reference | OpenAPI + ReDoc | Cleaner than Swagger UI. | | Search | Algolia | Fast, typo-tolerant. | | CI/CD | GitHub Actions | Auto-deploys on PR merge. |

4. Write & Structure Content

• Action: Follow these rules for each doc type:
• Tutorials:
  • Start with a clear goal (e.g., "By the end, you’ll have a working chatbot").
  • Use progressive disclosure (hide advanced details behind collapsible sections).
  • Include screenshots/GIFs for key steps.
  • Example: Twilio’s SMS Quickstart.
• Guides (How-Tos):
  • Solve one specific problem (e.g., "Handle pagination in API responses").
  • Use code snippets with copy buttons.
  • Link to reference docs for details.
  • Example: Stripe’s "Handle webhook signatures".
• Reference Docs:
  • Auto-generate from OpenAPI (but add human context).
  • Include real-world examples (e.g., "Here’s how to fetch a user’s orders").
  • Example: GitHub’s REST API docs.
• Authentication Docs:
  • Separate quickstart (e.g., "Get an API key in 2 steps") from concepts (e.g., "OAuth 2.0 flows").
  • Include error messages and troubleshooting.
  • Example: Auth0’s docs.

5. Add Interactive Elements

• Action: Reduce friction with:
• API Explorer: Embed Swagger UI or Postman so users can test endpoints.
  • Example: Stripe’s API reference lets you try calls live.
• Code Sandbox: Embed a REPL (e.g., CodePen, JSFiddle) for frontend SDKs.
• Feedback Buttons: "Was this helpful?" with thumbs up/down.
• Search: Algolia or a built-in SSG search.

6. Test & Iterate

• Action: Validate your portal with:
• Usability Testing: Watch a dev try to complete a task (e.g., "Integrate the API in 10 minutes").
• Analytics: Track page views, search queries, and "Was this helpful?" feedback.
• Developer Reviews: Have engineers review code examples for accuracy.
• Tool: Use Hotjar to record user sessions.

Common Mistakes

Tech Writing Interview / Portfolio Tips

Hiring managers look for these in dev portal projects:

1. Show You Understand Developer Needs

• What to say: "I interviewed 5 developers and found that 80% struggled with OAuth. So I rewrote the auth docs to separate ‘Quickstart’ from ‘Concepts.’"
• What to avoid: "I wrote docs based on the product spec." (Shows no user research.)

2. Differentiate Between Doc Types

• Tricky distinction: Tutorial vs. Guide vs. Reference
• Tutorial: "Build a chatbot with our API" (teaches by building).
• Guide: "Handle rate limits" (solves a specific problem).
• Reference: "GET /messages endpoint" (factual details).
• Portfolio tip: Include one of each in your samples.

3. Know Your Tools

• Swagger UI vs. ReDoc:
• Swagger UI: More interactive (try API calls live), but cluttered.
• ReDoc: Cleaner design, better for reference docs.
• Docusaurus vs. MkDocs:
• Docusaurus: Better for React-based sites (e.g., API docs with interactive elements).
• MkDocs: Simpler, great for Markdown-heavy docs.

4. Highlight Collaboration

• What to say: "I worked with engineers to auto-generate API docs from OpenAPI, then added human context via PRs."
• Portfolio tip: Include a GitHub PR where you improved docs based on developer feedback.

Quick Check Questions

1. A developer complains that the API docs are outdated. How would you ensure docs stay in sync with code?

Answer: Implement docs-as-code with CI/CD checks: - Store docs in Git alongside the code.
- Use OpenAPI to auto-generate reference docs from the spec.
- Add a pre-commit hook to validate docs against the API (e.g., Spectral for OpenAPI linting).
- Set up GitHub Actions to auto-deploy docs on merge to main.
Why? Docs-as-code ensures docs are treated like code—reviewed, tested, and deployed automatically.

2. A product manager asks you to add a new feature guide to the portal. How do you decide where it goes?

Answer: Map it to the user journey: - If it’s a step-by-step task (e.g., "Set up webhooks"), put it in Guides.
- If it’s a concept (e.g., "How webhooks work"), put it in Concepts or link from the guide.
- If it’s reference material (e.g., "Webhook payload schema"), auto-generate it from OpenAPI.
Why? Users expect to find content based on what they’re trying to do, not your product’s features.

3. A developer says, "Your docs are too verbose. I just want the code." How do you improve them?

Answer: Apply the progressive disclosure principle: - Start with minimal viable code (e.g., a curl example).
- Hide advanced details (e.g., error handling) behind collapsible sections.
- Use tabs for multiple languages (e.g., Python, Node.js, Go).
- Add a "Copy" button to code snippets.
Why? Devs skim first, then dive deeper if needed. Reduce friction by showing only what’s essential upfront.

Last-Minute Cram Sheet

1. IA = User Journey, Not Product Features ⚠️ Never organize docs by your team’s org chart.
2. Docs-as-Code = Git + Markdown + SSG (Docusaurus, MkDocs, Hugo).
3. OpenAPI → Auto-generate reference docs (Swagger UI, ReDoc), but add human context.
4. Tutorial ≠ Guide ≠ Reference (Tutorial = build, Guide = solve, Reference = facts).
5. Authentication docs go FIRST ⚠️ If devs can’t log in, they’ll leave.
6. Add interactive elements (API explorer, code sandbox, feedback buttons).
7. Test with real devs (usability testing, analytics, GitHub issues).
8. Changelog + Version Selector ⚠️ Devs need to know if APIs are changing.
9. Markdown quirks:
10. Code blocks: ```python (language for syntax highlighting).
11. Links: [text](url) (not <a href>).
12. Tables: Use | and --- for headers.
13. OpenAPI 2.0 vs. 3.0:
    • 2.0: swagger: "2.0", definitions (schemas), parameters (in path/query).
    • 3.0: openapi: 3.0.0, components/schemas, requestBody (for POST/PUT).
    • ⚠️ 3.0 is more flexible but has a steeper learning curve.

Portfolio-Ready Project Idea:
Redesign a poorly organized dev portal (e.g., a public API with buried docs). 1. Audit the current IA (card sorting).
2. Rewrite a tutorial/guide/reference.
3. Auto-generate API docs from OpenAPI.
4. Add interactive elements (Swagger UI, feedback buttons).
5. Host it on GitHub Pages/Netlify.
6. Write a case study: "How I Improved [API]’s Docs for Developers."