Technical Writing and Documentation 101: Building a Tech Writing Portfolio (Open‑source contributions, Sample docs)

Building a Tech Writing Portfolio (Open‑source contributions, Sample docs)

Building a Tech Writing Portfolio: Open-Source Contributions & Sample Docs

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

What This Is

A tech writing portfolio is a curated collection of your best documentation work—real-world examples, open-source contributions, and sample projects—that prove your ability to explain complex technical concepts clearly. It’s your most powerful tool for landing jobs, freelance gigs, or promotions.

Why it matters: Hiring managers don’t just want to hear you can write—they want to see it. A strong portfolio demonstrates your skills in API documentation, user guides, tutorials, and docs-as-code workflows. For example: - A Stripe-like API reference (with OpenAPI specs, curl examples, and error codes) shows you can document payment gateways.
- A cloud service getting-started guide (with screenshots, CLI commands, and troubleshooting tips) proves you can onboard users to AWS or Kubernetes.

Key Terms & Tools

• OpenAPI (formerly Swagger): A standard for describing REST APIs in YAML/JSON. Tools like Swagger UI or Redoc auto-generate interactive docs from the spec.
• Docs-as-Code: Treating docs like software—stored in Git, written in Markdown/AsciiDoc, built with static site generators (Sphinx, Docusaurus, MkDocs), and reviewed via pull requests (PRs).
• Static Site Generators (SSGs): Tools that convert Markdown/AsciiDoc into HTML websites (e.g., Hugo, Jekyll, Next.js). Used for docs sites like GitHub Pages or Netlify.
• Markdown: A lightweight markup language for formatting text (e.g., # Heading, bold, [link](url)). Used in GitHub, GitLab, and most docs-as-code workflows.
• AsciiDoc: A more powerful alternative to Markdown (supports tables, cross-references, and conditional content). Used in Antora and Asciidoctor.
• DITA (Darwin Information Typing Architecture): An XML-based standard for modular, reusable documentation. Used in enterprise tools like Oxygen XML Editor.
• Git/GitHub: Version control for docs. Key commands: git clone, git commit, git push, git pull request.
• Postman/Insomnia: API testing tools to validate endpoints before documenting them.
• Diátaxis Framework: A documentation system that categorizes content into tutorials, how-to guides, explanations, and reference (avoids mixing types).
• Linters: Tools like Vale or write-good that enforce style rules (e.g., passive voice, wordiness).
• Continuous Integration (CI): Automated workflows (e.g., GitHub Actions) that build and deploy docs on every commit.
• Sample Docs: Mock documentation projects (e.g., a fake API, a CLI tool, or a SaaS product) to showcase skills when you lack real-world work.

Step-by-Step: Building Your Portfolio

1. Choose Your Focus Areas

Decide what to showcase based on your goals: - API docs? → OpenAPI specs, curl examples, SDK snippets.
- User guides? → Step-by-step tutorials, screenshots, troubleshooting.
- Developer docs? → CLI references, SDK docs, architecture diagrams.
- Open-source? → Contribute to projects like Kubernetes, React, or VS Code.

Action: Pick 2-3 focus areas (e.g., API docs + user guides + open-source).

2. Create Sample Docs (If You Lack Real Work)

Option A: Fake a Product
- Invent a SaaS tool (e.g., "WeatherAlert API" or "TaskMaster CLI").
- Write: - A getting-started guide (tutorial).
- An API reference (OpenAPI spec + Swagger UI).
- A troubleshooting page (how-to guide).

Option B: Document a Real (But Undocumented) Tool
- Find an open-source project with poor docs (e.g., a GitHub repo with no README).
- Write a quickstart guide or API reference and submit a PR.

Example:

# WeatherAlert API Reference
## Get Weather by Location
Endpoint: `GET /weather?location={city}`
Parameters:
| Name      | Type   | Description               |
|-----------|--------|---------------------------|
| `location`| string | City name (e.g., "London")|

Example Request:
```bash
curl -X GET "https://api.weatheralert.com/weather?location=London" -H "Authorization: Bearer YOUR_API_KEY"

---

### 3. Contribute to Open Source
Where to find projects:
- Good First Issues: [GitHub "good first issue" label](https://github.com/topics/good-first-issue)
- Docs-Specific Repos:
  - [Kubernetes Docs](https://github.com/kubernetes/website)
  - [React Docs](https://github.com/reactjs/reactjs.org)
  - [VS Code Docs](https://github.com/microsoft/vscode-docs)

How to contribute:
1. Find a doc issue (e.g., "Add missing CLI command" or "Fix broken link").
2. Fork the repo and clone it locally.
3. Make changes (e.g., update a Markdown file).
4. Test locally (e.g., run `npm run dev` for Docusaurus sites).
5. Submit a PR with a clear title (e.g., "docs: Add missing `kubectl delete` example").

Pro Tip: Start with small fixes (typos, broken links) before tackling larger docs.

---

### 4. Host Your Portfolio
Option A: GitHub Pages (Free)
- Create a repo named `username.github.io`.
- Use Jekyll or Docusaurus to build a static site.
- Add:
  - A homepage (bio + links to projects).
  - A projects folder (PDFs, Markdown files, or embedded docs).

Option B: Netlify/Vercel (Free)
- Drag-and-drop a folder of HTML/Markdown files.
- Auto-deploys from GitHub.

Option C: Notion/Google Docs (Quick & Dirty)
- Link to PDFs or live docs (e.g., Google Docs with "Anyone with the link can view").

Example Portfolio Structure:

portfolio/ ├── index.md # Homepage (bio + links) ├── api-docs/ # Sample API reference │ ├── openapi.yaml # OpenAPI spec │ └── index.html # Swagger UI ├── user-guide/ # Getting-started guide │ ├── images/ # Screenshots │ └── guide.md # Tutorial └── open-source/ # PR links + screenshots ```

5. Polish & Optimize for Hiring Managers

• Add context: For each project, write a 1-paragraph summary (e.g., "Wrote a getting-started guide for a fake CLI tool, using Markdown and GitHub Pages").
• Show process: Include before/after screenshots of open-source contributions.
• Link to live docs: If possible, host your sample docs (e.g., Netlify).
• Include metrics: "Improved API doc readability by 30% based on user feedback."

Common Mistakes

Tech Writing Interview / Portfolio Tips

What Hiring Managers Look For

1. Clarity > Perfection
2. Can you explain a complex concept in plain language? (e.g., "What is OAuth?" in 3 sentences).

3. Avoid jargon unless you define it.

4. Diátaxis Framework

5. Tutorial (teaches by building, e.g., "Build a To-Do App with React").
6. How-to Guide (solves a specific problem, e.g., "Deploy to AWS in 5 Steps").
7. Explanation (conceptual, e.g., "How JWT Tokens Work").
8. Reference (dry, factual, e.g., API endpoint list).

9. ⚠️ Don’t mix them! A tutorial shouldn’t include API reference material.

10. OpenAPI vs. Swagger UI vs. Redoc

11. OpenAPI = The spec (YAML/JSON file).
12. Swagger UI = Interactive docs (good for testing).

13. Redoc = Prettier, more readable (good for end users).

14. Docs-as-Code Workflow

15. Know how to:
    • Write in Markdown/AsciiDoc.
    • Use Git (clone, commit, push, PR).
    • Run a static site generator (e.g., npm run dev for Docusaurus).

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—store docs in Git, auto-generate OpenAPI specs from code annotations, and use GitHub Actions to rebuild docs on every commit.
Why? This ensures docs are always up-to-date with the codebase.

2. You’re asked to write a tutorial for a new CLI tool. What’s the first thing you do?

Answer: Test the tool yourself—run the commands, note errors, and identify the happy path (the simplest successful workflow).
Why? You can’t write a tutorial without firsthand experience.

3. A hiring manager asks, "How do you handle feedback from engineers?" What’s your answer?

Answer: Treat feedback like code reviews—address technical inaccuracies first, then clarify ambiguous language. Use GitHub PRs for transparency.
Why? Engineers care about accuracy; writers care about clarity. Balance both.

Last-Minute Cram Sheet

1. OpenAPI 3.0 vs 3.1: 3.1 adds webhooks and better JSON Schema support.
2. Markdown tables: Use | Header | Header | and |------|------| for alignment.
3. GitHub Flavored Markdown (GFM): Supports task lists (- [x] Done).
4. Docusaurus: Run npx docusaurus init to start a docs site.
5. Vale: Lint docs with vale sync and vale yourfile.md.
6. Diátaxis: Tutorials teach, how-tos solve, explanations clarify, references list.
7. ⚠️ Avoid passive voice (e.g., "The button was clicked" → "Click the button").
8. Swagger UI: Auto-generates from OpenAPI; Redoc is prettier but less interactive.
9. Docs-as-code tools: Git, Markdown, SSGs (Sphinx, Docusaurus), CI (GitHub Actions).
10. Portfolio must-haves: API docs, user guide, open-source PR, and a clear bio.

Final Tip: Your portfolio is a living document—update it every 3-6 months with new samples or open-source contributions. Happy writing! ?