Technical Writing and Documentation 101: Resume and Interviewing for Tech Writers (Writing Test, Portfolio Walkthrough)

Resume and Interviewing for Tech Writers (Writing Test, Portfolio Walkthrough)

Resume & Interviewing for Tech Writers: Writing Test & Portfolio Walkthrough

A Practical Study Guide for Aspiring and Transitioning Technical Writers

What This Is

A writing test and portfolio walkthrough are the two most critical filters in a tech writing interview. The writing test evaluates your ability to explain complex concepts clearly, structure information logically, and adapt to style guidelines—skills that directly impact developer productivity and user adoption. For example, a well-structured API reference page for Stripe’s payment gateway (with clear endpoints, request/response examples, and error codes) can reduce support tickets by 30% and accelerate integration time for developers.

Your portfolio is your proof of work—it demonstrates not just what you’ve written, but how you think about documentation as a product. A strong portfolio walkthrough shows hiring managers that you understand docs-as-code workflows, user-centered design, and collaboration with engineers, which are essential for modern tech writing roles.

Key Terms & Tools

• Writing Test (Take-Home or Live):
  A timed or untimed assignment where you write, edit, or restructure documentation (e.g., a tutorial, API reference, or troubleshooting guide). Often includes a style guide and sample code/API to work with.
  Tools: Markdown, Google Docs, Confluence, Swagger/OpenAPI, Postman (for API testing).

• Portfolio:
  A curated collection of your best documentation work, hosted on a personal website, GitHub, or a platform like GitBook or Read the Docs. Should include real-world examples (e.g., API docs, CLI guides, conceptual overviews) and case studies explaining your process.
  Tools: GitHub Pages, MkDocs, Docusaurus, Notion (for case studies).

• Docs-as-Code:
  Treating documentation like software—stored in Git, written in Markdown/AsciiDoc, built with static site generators (e.g., Sphinx, Hugo, Docusaurus), and reviewed via pull requests (PRs).
  Example: A team uses GitHub + MkDocs to version-control docs and auto-deploy updates.

• OpenAPI (Swagger):
  A standard for describing REST APIs in a machine-readable format (YAML/JSON). Enables auto-generated docs (e.g., Swagger UI, ReDoc) and interactive API explorers.
  Tools: Swagger Editor, Stoplight, Redocly.

• DITA (Darwin Information Typing Architecture):
  An XML-based standard for modular documentation, often used in enterprise settings (e.g., hardware, medical devices). Supports single-sourcing (reusing content across guides).
  Tools: Oxygen XML Editor, FrameMaker, DITA-OT.

• Conceptual vs. Task-Based Docs:

• Conceptual: Explains why and how things work (e.g., "How OAuth 2.0 Works").

• Task-Based (How-To/Tutorial): Step-by-step instructions for doing something (e.g., "Integrate OAuth in 5 Steps").
  ⚠️ Mistake: Mixing the two (e.g., burying a tutorial in a conceptual overview).

• Reference Docs:
  Structured, exhaustive documentation (e.g., API endpoints, CLI commands, error codes). Often auto-generated from code (e.g., Javadoc, Sphinx, Swagger).
  Example: AWS CLI reference or Stripe’s API docs.

• Style Guide:
  A set of rules for consistency in tone, grammar, formatting, and terminology. Common guides:

• Google Developer Documentation Style Guide (tech-focused)
• Microsoft Writing Style Guide (enterprise)

• IBM Style Guide (formal/technical)

• Markdown:
  A lightweight markup language for formatting text (e.g., # Headers, bold, - lists). Used in GitHub, GitLab, and docs-as-code tools.
  Example: markdown ## Install the CLI Run `npm install -g my-cli` to install globally.

• Static Site Generators (SSGs):
  Tools that convert Markdown/AsciiDoc into fast, version-controlled websites for docs.
  Popular SSGs:

• MkDocs (Python, simple)
• Docusaurus (React, great for APIs)
• Hugo (fast, flexible)

• Sphinx (Python, supports reStructuredText)

• User-Centered Documentation:
  Docs designed around user goals (e.g., "I want to deploy a container") rather than product features (e.g., "Our container service has X, Y, Z").
  Example: Instead of "Our API supports pagination," write: "How to fetch large datasets using pagination."

• PR (Pull Request) Review for Docs:
  The process of collaborating with engineers to review docs changes (e.g., fixing inaccuracies, adding missing parameters). Critical in docs-as-code workflows.
  Example: A PR comment: "This endpoint now requires an api_key parameter—update the example."

Step-by-Step: Acing the Writing Test & Portfolio Walkthrough

1. Preparing for the Writing Test

Action Steps:
1. Clarify the requirements (ask for the style guide, audience, and format upfront).
- Example question: "Is this for end-users or developers? Should I follow the Google or Microsoft style guide?" 2. Analyze the prompt (identify the doc type: tutorial, API reference, troubleshooting guide, etc.).
- Example: If it’s an API doc, note the endpoints, parameters, and error codes you need to cover.
3. Test the product/API (if possible) to ensure accuracy.
- Tools: Postman (APIs), terminal (CLI), or the product itself.
4. Outline first (use a hierarchy: H1 → H2 → H3 → steps/bullet points).
- Example outline for a tutorial:
# Deploy a Container
## Prerequisites
## Step 1: Install the CLI
## Step 2: Authenticate
## Step 3: Deploy
## Troubleshooting 5. Write for scannability (short paragraphs, bold key terms, code blocks, tables).
6. Self-edit (check for active voice, consistent terminology, and logical flow).
- Tool: Use Hemingway Editor or Grammarly for readability.
7. Submit with a README (if allowed) explaining your choices (e.g., "I used a task-based approach because the audience is beginners").

2. Building a Portfolio (Before the Interview)

Action Steps:
1. Select 3–5 strong samples (mix of conceptual, task-based, and reference docs).
- Example portfolio pieces:
- A tutorial (e.g., "Build a Slack Bot in Python")
- An API reference (e.g., "Stripe Payments API Endpoints")
- A troubleshooting guide (e.g., "Common Kubernetes Errors")
- A case study (e.g., "How I Improved Our Docs’ SEO by 40%") 2. Host it professionally (use GitHub Pages, Netlify, or Read the Docs).
- Example: https://yourname.github.io/docs-portfolio 3. Add context (for each sample, include a 1-paragraph case study explaining):
- The problem (e.g., "Users struggled with OAuth setup")
- Your solution (e.g., "I restructured the guide into a step-by-step tutorial")
- The impact (e.g., "Reduced support tickets by 25%") 4. Include a "Process" page (show how you work):
- Tools you use (e.g., "Markdown + MkDocs + GitHub")
- How you collaborate (e.g., "PR reviews with engineers")
- Your style guide preferences (e.g., "Google Style Guide for tech docs")

3. Portfolio Walkthrough (During the Interview)

Action Steps:
1. Prepare a 5-minute pitch (structure it like this):
- Hook: "I’ll walk you through 3 key pieces in my portfolio that show my range as a technical writer."
- Sample 1: "This API reference for a payment gateway demonstrates my ability to auto-generate docs from OpenAPI and write clear endpoint descriptions."
- Sample 2: "This troubleshooting guide for Kubernetes shows how I diagnose user pain points and structure solutions for scannability."
- Sample 3: "This case study explains how I improved our docs’ SEO by restructuring content for search intent."
- Close: "I’d love to hear which of these resonates most with the role you’re hiring for." 2. Anticipate questions (prepare answers for):
- "Why did you choose this structure?"
- "How did you collaborate with engineers?"
- "How would you improve this doc today?" 3. Show, don’t just tell (if possible, live-demo a doc you’ve written).
- Example: "Here’s how I used Swagger UI to make this API interactive."

Common Mistakes

Tech Writing Interview & Portfolio Tips

What Hiring Managers Evaluate

1. Clarity > Perfection
2. They care more about logical structure and user-focused writing than flawless grammar.

3. Example: A well-organized tutorial with a few typos beats a perfectly polished but confusing doc.

4. Collaboration with Engineers

5. Can you work with devs to clarify specs, review PRs, and keep docs in sync with code?

6. Tip: Mention PR reviews, Slack/email threads with engineers, or docs-as-code workflows in your portfolio.

7. Tool Flexibility

8. Are you comfortable with Markdown, Git, and static site generators? Can you learn new tools quickly?

9. Tip: If you’ve only used Google Docs, set up a GitHub Pages site for your portfolio.

10. User Empathy

11. Can you anticipate user pain points? Do you write for beginners vs. experts differently?
12. Example: A hiring manager might ask, "How would you explain OAuth to a non-technical user?"

Tricky Distinctions to Know

Quick Check Questions

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

Answer:
Set up a docs-as-code workflow with automated checks (e.g., CI/CD pipelines that fail builds if docs don’t match the OpenAPI spec) and regular PR reviews with engineers.
Why? Manual updates are error-prone; automation and collaboration reduce drift.

2. You’re asked to write a tutorial for a CLI tool. What’s the first question you’d ask the hiring manager?

Answer:
"Who is the audience, and what’s their goal?" (e.g., "Are they beginners who need hand-holding, or experienced devs who want speed?") Why? Audience and goal determine structure, depth, and tone.

3. A hiring manager says, "Show me a time you improved documentation." What’s a strong response?

Answer:
Describe a specific problem, your solution, and the impact (e.g., "Users struggled with our OAuth setup guide, so I restructured it into a step-by-step tutorial with screenshots. Support tickets dropped by 30%.").
Why? Hiring managers want measurable results, not just "I wrote docs."

Last-Minute Cram Sheet

1. ⚠️ Tutorial ≠ How-To Guide – A tutorial teaches by building; a how-to solves a specific problem.
2. Docs-as-Code = Git + Markdown + SSG (e.g., MkDocs, Docusaurus).
3. OpenAPI 3.0 vs 2.0 – 3.0 supports callbacks, links, and better examples.
4. Google Style Guide Rule: Use second person ("You can deploy...") and active voice.
5. Markdown Cheat Sheet:
6. # H1, ## H2, ### H3
7. bold, *italic*, `code`
8. - list or 1. list
9. [link](url)
10. ⚠️ Avoid "click here" – Use descriptive links (e.g., "Download the CLI" vs. "Click here").
11. API Docs Must-Haves: Endpoint, parameters, request/response examples, error codes.
12. DITA = XML for modular docs (used in enterprise/hardware).
13. Static Site Generators (SSGs): MkDocs (simple), Docusaurus (APIs), Hugo (fast).
14. PR Reviews for Docs: Engineers catch inaccuracies; writers catch clarity issues.

Final Tip: In your portfolio, show your process—hiring managers want to see how you think, not just what you’ve written. Good luck! ?