Scientyfic World

Technical Writing Portfolio: How to Build One (With Samples)

Build a technical writing portfolio that gets interviews: which samples to include, how to make them with no experience, and one sample built step by step....
Share:

Get an AI summary of this article

Technical writing portfolio banner: samples, context and hosting

A technical writing portfolio is the single most useful thing you can show a hiring manager: a small, well-chosen set of writing samples that proves you can explain technical things clearly to a specific audience. This guide covers which samples to include, how to create strong ones when you have no professional work you can share, how to present each sample, and where to host the portfolio. We also built one complete sample from scratch, an API reference, and show every step.

About the example: we built the sample API and ran every request in its reference on 20 November 2026 on macOS 27.2 with Node.js 23.11 and curl. We set up the portfolio folder structure in a local Git repository but did not publish it to a hosting service, so the hosting steps are described, not tested here. The API is a teaching sample, not a real product.

TL;DR

  • Aim for 3 to 5 strong samples, not 15 average ones. Each should show a different type of document.
  • Match the samples to the jobs you want: API docs for developer-docs roles, user guides for product roles, and so on.
  • No shareable work? Document an open-source project or a tool you built yourself. Never post work you do not have rights to.
  • Put a short card above every sample: type, audience, tools, what you did, what it shows.
  • Host it somewhere a reviewer can open in one click, such as a GitHub repository, a simple site, or a single PDF.

What Hiring Managers Look For in a Technical Writing Portfolio

Reviewers rarely read every word. They skim a sample or two, looking for evidence that you can do the specific job. The Write the Docs hiring guide gives similar advice: include samples you are proud of that show a skill, domain knowledge or good technique, keep them short, tailor the set to the role, and add a short description of each piece and your process.

In practice, a reviewer is checking for:

  • Audience awareness. Is it obvious who the document is for, and does it give that reader what they need, in the order they need it?
  • Accuracy. Do the code samples look like they were actually run? Are steps complete?
  • Structure. Headings, lists, tables and code blocks used where they help scanning.
  • Clear, plain sentences. Short paragraphs, active voice, consistent terms.
  • Range. More than one document type, so they can picture you on their docs set.

If you are new to the field, our overview of what technical writing is explains the main document types and the audiences they serve.

Which Technical Writing Samples to Include

Pick samples that cover different types of documentation, then weight the set toward the jobs you are applying for. This table shows common sample types and what each one proves.

Sample typeWhat it provesBest for roles in
API referenceYou can document endpoints, parameters and errors preciselyDeveloper documentation, API platforms
How-to or tutorialYou can turn a task into clear, ordered stepsAlmost every role
QuickstartYou can get a new user to a first result fastDeveloper tools, SaaS
READMEYou can explain a project’s purpose, setup and usage on one pageOpen source, developer tools
Release notesYou can explain changes in terms of user impactProduct and SaaS teams
Conceptual overviewYou can explain how something works without hand-wavingComplex platforms, data, security
Before-and-after rewriteYou can edit and improve existing contentContent teams, docs maintenance

A solid starter set is three samples: one reference document (such as an API reference), one task-based document (a how-to or developer quickstart), and one that shows editing or product sense (a rewrite or release notes). Add more only when they show something the first three do not.

How to Create Samples With No Work Experience

Most professional documentation belongs to an employer or client, and you cannot post it without written permission. The Write the Docs guide is clear that you should not include writing you have no rights to; if an owner does give permission, follow any restrictions they set, such as removing sensitive details. If you have nothing you can share, create your own samples:

  • Document something you built. A small script, API or app gives you full control and real code to test. This is what we do in the walkthrough below.
  • Contribute to an open-source project. Fix a confusing README section or write a missing how-to, then link to the merged pull request. It shows you can work with maintainers and a real review process.
  • Document a tool you use every day. A how-to for a command-line tool, editor feature or API you know well.
  • Rewrite a weak page. Take a public page with clear problems and show your improved version next to the original, with a short note on what you changed and why. Do not present the original as yours.
  • Use course exercises as a starting point. Google’s technical writing courses (Technical Writing One and Two, plus courses on accessibility and error messages) give you practice material you can build on.

Whatever you choose, test it. A tutorial whose commands fail on the first step does more harm than having no sample at all. Writing for a real open-source project also builds the network and track record that lead to paid work, which we cover in how to make money from technical writing.

Walkthrough: Building One Real Sample From Scratch

To show what “create your own sample” looks like in practice, we built a tiny notes API and wrote its reference documentation. The whole sample took one sitting and covers everything a reviewer of API docs looks for: endpoints, request fields, real responses and error codes.

Step 1: Build or pick something small to document

Here is the complete API: a single Node.js file with no dependencies. It stores notes in memory, so nothing is saved after you stop it. Save it as server.mjs.

// notes-api: a tiny in-memory API used as a documentation sample.
import http from "node:http";

const notes = new Map();
let nextId = 1;

const send = (res, status, body) => {
  res.writeHead(status, { "Content-Type": "application/json" });
  res.end(JSON.stringify(body));
};

http.createServer((req, res) => {
  if (req.method === "GET" && req.url === "/health") return send(res, 200, { status: "ok" });

  if (req.method === "POST" && req.url === "/notes") {
    let raw = "";
    req.on("data", (c) => (raw += c));
    req.on("end", () => {
      let body;
      try { body = JSON.parse(raw); } catch { return send(res, 400, { error: "invalid_json" }); }
      if (typeof body.text !== "string" || body.text.trim() === "")
        return send(res, 422, { error: "text_required" });
      const note = { id: nextId++, text: body.text, created_at: new Date().toISOString() };
      notes.set(note.id, note);
      send(res, 201, note);
    });
    return;
  }

  const m = req.url.match(/^\/notes\/(\d+)$/);
  if (req.method === "GET" && m) {
    const note = notes.get(Number(m[1]));
    return note ? send(res, 200, note) : send(res, 404, { error: "not_found" });
  }

  send(res, 404, { error: "not_found" });
}).listen(3000, () => console.log("notes-api listening on http://localhost:3000"));

Step 2: Run it and capture real requests and responses

Start the server with node server.mjs, then call every endpoint from a second terminal, including the error cases. Copy the exact output; never type responses from memory. This is what we got:

$ node server.mjs
notes-api listening on http://localhost:3000

$ curl -s http://localhost:3000/health
{"status":"ok"}
$ curl -s -X POST http://localhost:3000/notes -H "Content-Type: application/json" -d '{"text":"Ship the v2 docs"}'
{"id":1,"text":"Ship the v2 docs","created_at":"2026-11-20T05:09:07.603Z"}
$ curl -s http://localhost:3000/notes/1
{"id":1,"text":"Ship the v2 docs","created_at":"2026-11-20T05:09:07.603Z"}
$ curl -s -w " %{http_code}" -X POST http://localhost:3000/notes -H "Content-Type: application/json" -d '{"text":""}'
{"error":"text_required"} 422
$ curl -s -w " %{http_code}" -X POST http://localhost:3000/notes -d 'not json'
{"error":"invalid_json"} 400
$ curl -s -w " %{http_code}" http://localhost:3000/notes/99
{"error":"not_found"} 404

Your created_at value will differ, because it is the time the note was created.

Step 3: Write the reference

Now turn those results into documentation. Keep the same structure for every endpoint (what it does, request, example, response) and document every error the code can return. This is the finished sample, written in Markdown:

# Notes API reference

Base URL: `http://localhost:3000`
All responses are JSON. Requests with a body must send
`Content-Type: application/json`.

## GET /health

Checks that the service is running.

```bash
curl -s http://localhost:3000/health
```

Response `200 OK`:

```json
{"status":"ok"}
```

## POST /notes

Creates a note.

| Field | Type   | Required | Description                    |
|-------|--------|----------|--------------------------------|
| text  | string | yes      | Note content. Cannot be empty. |

```bash
curl -s -X POST http://localhost:3000/notes \
  -H "Content-Type: application/json" \
  -d '{"text":"Ship the v2 docs"}'
```

Response `201 Created`:

```json
{"id":1,"text":"Ship the v2 docs","created_at":"2026-11-20T05:09:07.603Z"}
```

## GET /notes/{id}

Returns one note by its numeric ID.

```bash
curl -s http://localhost:3000/notes/1
```

Response `200 OK`: the note object, as above.

## Errors

| Status | `error` value   | When it happens                         |
|--------|-----------------|-----------------------------------------|
| 400    | `invalid_json`  | The request body is not valid JSON      |
| 422    | `text_required` | `text` is missing, not a string, or empty |
| 404    | `not_found`     | No note has that ID, or unknown path    |

Check the reference against the code one last time: every status code in the errors table appears in server.mjs, and every example request is one we ran. That cross-check is the habit reviewers are looking for.

How to Present Each Sample

A raw document with no context makes the reviewer guess what you did. Put a short card at the top of each sample instead. Here is the card for the sample above:

## Notes API reference

**Type:** API reference (REST)
**Audience:** Backend developers integrating with the API
**Tools:** Markdown, curl, Node.js 23
**What I did:** Built a small API, then wrote the reference from scratch.
Every request and response below was run and copied from a real terminal.
**What it shows:** Consistent endpoint structure, error documentation,
copy-paste examples.
**Time spent:** About 4 hours

The “What I did” line matters most when a sample came from a team project: say exactly which parts you wrote, edited or tested. For a rewrite, link to the original and show a short before-and-after excerpt. For a contribution, link to the pull request.

Where to Host Your Technical Writing Portfolio

The best host is whatever a reviewer can open in one click, with no sign-in. Common options:

OptionGood forWatch out for
GitHub repositoryDeveloper-docs roles; shows Git and Markdown skillsReviewers outside engineering may find it less friendly
Personal site or static site generatorFull control over design and navigationSetup and upkeep time; broken links if left unmaintained
Blogging platformFast to start; built-in reading experienceLess control over structure; mixed with unrelated posts
Single PDFApplications that ask for an attachmentLong files are hard to skim; code blocks must stay readable
Cloud drive folderQuick sharing of existing documentsPermission settings that lock reviewers out

For a GitHub-based portfolio, a simple layout like this works well. GitHub renders a folder’s README.md below the file list when someone opens that folder, so each sample can live in its own README (see GitHub’s documentation on READMEs for how READMEs are displayed). We did not publish this repository, so check the rendering in your own account:

tech-writing-portfolio/
├── README.md                  # the landing page: who you are + sample list
└── samples/
    ├── api-reference/
    │   ├── README.md          # the sample itself
    │   └── server.mjs         # the code it documents
    ├── how-to/
    │   └── README.md
    ├── release-notes/
    │   └── README.md
    └── rewrite/
        └── README.md          # before/after edit of an existing doc

The top-level README is your landing page: two or three sentences about you and the roles you want, then a list of samples with one line each and a link. Our guide to writing a great README covers the structure that works for that page too.

Portfolio Checklist Before You Send It

  • 3 to 5 samples, each a different document type, weighted toward the target role.
  • Every code sample and command tested, with real output.
  • A context card on each sample: type, audience, tools, what you did, what it shows.
  • No confidential or unlicensed material; written permission for any client work.
  • Every link opens without a sign-in, checked in a private browser window.
  • Proofread: spelling, consistent terms, consistent heading style.
  • A short landing page with your name, focus and a way to contact you.
  • A date or “last updated” note, and a reminder to refresh samples every few months.

Conclusion

A technical writing portfolio does not need to be large. Three to five tested samples, each with a short card explaining the audience and your role, will tell a hiring manager more than a long list of links. If you have no shareable work yet, build something small, document it properly, and use that as your first sample, as we did with the notes API. Then add an open-source contribution and a rewrite, and you have a portfolio that covers reference, task and editing skills.

Frequently Asked Questions

How many samples should a technical writing portfolio have?

Three to five strong samples is enough for most applications. Choose different document types, such as an API reference, a how-to and a rewrite, and put the ones most relevant to the job first.

How do I build a technical writing portfolio with no experience?

Create your own samples: document a small tool or API you built, contribute documentation to an open-source project, write a how-to for a tool you know well, or rewrite a weak public page and explain your changes.

Can I include work I did for a previous employer?

Only with explicit written permission from the owner, and only within any limits they set, such as removing sensitive details. Otherwise, create comparable samples of your own instead.

Should my technical writing portfolio be a website or a PDF?

Either works if a reviewer can open it in one click without signing in. A website or GitHub repository is easier to keep current and suits developer-docs roles; a PDF is useful when an application asks for an attachment.

What should I write about each sample?

Add a short card with the document type, intended audience, tools used, exactly what you did, and what the sample shows. For team work, say which parts were yours.

How often should I update my portfolio?

Review it every few months and whenever you finish a piece you are proud of. Replace older or weaker samples rather than letting the list grow, and recheck that every link still works.

Snehasish Konger
Developed @scientyficworld.org | Technical writer @Nected | Content Developer
Connect with Snehasish Konger

On This page

Take a Pause with Intervals

A Sunday letter on building, writing, and thinking deeper as a developer — short, honest, and worth your time.

Snehasish Konger profile photo

"Hey there — I'm Snehasish. Hope this post saved you some head-scratching time! I've spent years turning technical chaos into clarity, and I'm here to be your guide through the maze of modern tech. Stick around for more lightbulb moments — we're just getting started."

Related Posts