Technical Writing and Documentation 101: What is Technical Writing (Roles, Deliverables, Industries)

What is Technical Writing (Roles, Deliverables, Industries)

Technical Writing Study Guide: Roles, Deliverables, and Industries

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

What This Is

Technical writing bridges the gap between complex systems and their users—whether they’re developers, end-users, or internal teams. It ensures people can use technology effectively, not just understand it. A well-written API reference (like Stripe’s payment API docs) or a getting-started guide (like AWS’s "Launch a Virtual Server" tutorial) can mean the difference between a frustrated user and a successful one. For example, Stripe’s API docs include interactive code samples, error explanations, and versioning notes—all designed to help developers integrate payments in minutes, not hours.

Key Terms & Tools

• API Documentation: Instructions for developers on how to use an API (e.g., endpoints, parameters, authentication). Tools: OpenAPI/Swagger, Postman, Redoc, Stoplight.
• User Manuals/Guides: Step-by-step instructions for end-users (e.g., "How to Set Up Your Smart Thermostat"). Tools: MadCap Flare, Confluence, Markdown + static site generators (Docusaurus, MkDocs).
• Conceptual Documentation: Explains why and how a system works (e.g., "How Kubernetes Scheduling Works"). Often paired with diagrams (Mermaid, Lucidchart) or whitepapers.
• Tutorials: Hands-on guides that teach by building (e.g., "Build a To-Do App with React"). Contrast with how-to guides (task-focused, e.g., "Deploy a React App to Vercel").
• Reference Docs: Structured, exhaustive details (e.g., CLI command flags, API endpoint parameters). Think "dictionary" vs. "cookbook."
• Docs-as-Code: Treating docs like code—stored in Git, written in Markdown/AsciiDoc, built with static site generators (SSGs), and reviewed via pull requests (PRs). Tools: Sphinx, Hugo, Vitepress, GitHub/GitLab Pages.
• DITA (Darwin Information Typing Architecture): An XML-based standard for modular, reusable documentation. Used in enterprise (e.g., IBM, Cisco). Tools: Oxygen XML, FrameMaker.
• OpenAPI (Swagger): A specification for describing REST APIs. Enables auto-generated docs (Swagger UI, Redoc) and client SDKs. Example: Stripe’s OpenAPI spec.
• Markdown: Lightweight markup language for docs. Syntax quirks: bold vs. __bold__, - vs. * for lists. Extensions: GitHub Flavored Markdown (GFM), Mermaid diagrams.
• Static Site Generators (SSGs): Tools that convert Markdown/AsciiDoc into HTML websites. Examples: Docusaurus (Facebook), MkDocs (Python), Next.js (React).
• Diátaxis Framework: A methodology for structuring docs into 4 types: tutorials, how-to guides, reference, and explanation. Learn more here.
• Style Guides: Rules for consistency (e.g., Google Developer Documentation Style Guide, Microsoft Writing Style Guide). Covers tone, grammar, and formatting.

Step-by-Step: How to Create a Deliverable (Example: API Docs)

1. Gather Requirements
2. Read the API spec (OpenAPI/Swagger file) or talk to engineers.
3. Identify the audience (e.g., junior devs vs. enterprise architects).

4. Example: For a payment API, note endpoints like /charges, /customers, and /refunds.

5. Test the API

6. Use Postman or curl to call endpoints. Document:
   • Required/optional parameters.
   • Success/error responses (e.g., 200 OK, 400 Bad Request).
   • Rate limits (e.g., "100 requests/minute").

7. Example: Test POST /charges with a test API key to see the response format.

8. Draft the Content

9. Write in Markdown (for docs-as-code) or DITA/XML (for enterprise).
10. Structure:
    • Overview (what the API does).
    • Authentication (API keys, OAuth).
    • Endpoints (methods, parameters, examples).
    • Error codes (e.g., 402 Payment Required).

11. Example: For /charges, include a curl example:
    bash
curl https://api.example.com/charges \
-H "Authorization: Bearer sk_test_123" \
-d amount=1000 \
-d currency=usd

12. Add Visuals

13. Diagrams: Use Mermaid or Lucidchart to show workflows (e.g., "Payment Flow").
14. Screenshots: For UI-based docs (e.g., "Click ‘Deploy’ in the AWS Console").

15. Example: A sequence diagram for a payment API:
    mermaid
sequenceDiagram
Developer->>API: POST /charges
API->>Bank: Process payment
Bank-->>API: Success
API-->>Developer: 200 OK

16. Review & Iterate

17. Submit a PR for developer review (docs-as-code).
18. Use linters (e.g., Vale, markdownlint) to catch style errors.

19. Example: A developer flags that the amount parameter should be in cents, not dollars—update the docs.

20. Publish & Maintain

21. Deploy via GitHub Pages, Netlify, or Read the Docs.
22. Set up CI/CD (e.g., GitHub Actions) to auto-build docs on merge.
23. Example: Stripe’s docs auto-update when their OpenAPI spec changes.

Common Mistakes

Tech Writing Interview / Portfolio Tips

1. Show, Don’t Tell

2. Hiring managers want to see deliverables, not just resumes. Include:

   
   
   • A GitHub repo with docs-as-code (e.g., a Docusaurus site).
   • A PDF portfolio with samples (API docs, tutorials, diagrams).
   • A case study (e.g., "How I Improved Our API Docs’ Adoption by 30%").

3. Master the Distinctions

4. Reference vs. Guide:
   • Reference: Exhaustive (e.g., "All CLI flags for git commit").
   • Guide: Task-focused (e.g., "How to Squash Commits").

5. Swagger UI vs. Redoc:

   
   
   • Swagger UI: Interactive (try API calls in-browser).
   • Redoc: Static, prettier, better for reference docs.

6. Prepare for Scenario Questions

7. "How would you document a breaking API change?"

   
   
   • Answer: Version the docs, add deprecation warnings, and provide migration guides (e.g., Stripe’s migration docs).

8. Know the Tools

9. Be ready to discuss:
   • Docs-as-code workflows (Git, PRs, CI/CD).
   • Static site generators (Docusaurus vs. MkDocs).
   • API tools (Postman, OpenAPI, Swagger UI).

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 docs-as-code with CI/CD (e.g., GitHub Actions) to auto-build docs on merge, and use OpenAPI to auto-generate API reference docs from the spec.

3. Why: Manual updates are error-prone; automation reduces drift.

4. You’re writing a tutorial for a cloud storage API. Should you include a section on "How to Handle Rate Limits"?

5. Answer: No—this belongs in a how-to guide or reference doc. Tutorials should focus on teaching core concepts (e.g., "Upload Your First File").

6. Why: The Diátaxis framework separates tutorials (learning) from how-to guides (solving problems).

7. Your team uses DITA for enterprise docs. Why might they prefer it over Markdown?

8. Answer: DITA supports modularity (reusable topics), conditional content (e.g., "show this for admins only"), and enterprise workflows (e.g., translation management).
9. Why: Markdown is simpler but lacks DITA’s scalability for large, complex docs.

Last-Minute Cram Sheet

1. Docs-as-code = Git + Markdown + SSG + PRs.
2. OpenAPI 3.0 vs. 2.0: 3.0 supports callbacks, links, and better examples.
3. ⚠️ Tutorial ≠ How-to guide: Tutorials teach concepts; how-to guides solve problems.
4. Markdown quirks: - for lists, --- for horizontal rules, `code` for inline code.
5. Google Style Guide rule: Use second person ("You can…") and active voice ("Click Submit" vs. "The Submit button should be clicked").
6. API docs must-haves: Authentication, endpoints, parameters, examples, error codes.
7. Diátaxis framework: Tutorials, how-to guides, reference, explanation.
8. ⚠️ "Just write it like a blog" = bad. Docs need structure (e.g., Diátaxis) and precision.
9. Static site generators: Docusaurus (React), MkDocs (Python), Hugo (fast).
10. CI/CD for docs: GitHub Actions, Netlify, Read the Docs.

Portfolio Tip: Create a one-page "Docs Audit" for a popular tool (e.g., GitHub’s API docs) with 3 improvements (e.g., "Add a rate limit warning to /repos"). Include before/after screenshots.