When people are interested in pivoting to tech writing, one of the largest obstacles is not having a portfolio of writing samples, often required as part of the job application process.

Building a portfolio can actually be very straightforward and a useful exercise to confirm you’ll enjoy the role if you do get hired.

Portfolio basics

What does a portfolio include?

This varies based on how senior you are and what type of roles you’re applying for, but target 2-3 pieces to start.

Ideally, they’ll be an assortment of different types and lengths such as 1 short Quickstart/README, 1 medium how-to, and 1 longer doc. At least one doc should utilize code samples/snippets or bash commands.

Format the docs using Markdown.

Apply a style guide to your portfolio

Larger companies typically have their own style guide. It doesn’t particularly matter what style guide you use, but apply it consistently across your entire portfolio. Google and Microsoft have detailed publicly available style guides.

Where to put your portfolio?

A common (and simple) approach is to make a public GitHub repository and store your writing samples there as markdown (.md) files. A public GitHub Gist is also a simple way to provide someone a URL to read a rendered version of your Markdown.

GitHub and Markdown are basic skills expected of most tech writers. If these aren’t familiar to you, spend some time searching online as there are many tutorials available.

Crafting your writing samples

What writing have you already done?

Depending what role you’re pivoting from, you may already have writing samples that could be lightly tweaked and be suitable for your portfolio.

Many folks transition from some other writing heavy job such as academia, science writing, grant writing, or law. You could use one sample of this type of work in your portfolio.

Make sure you edit it so it doesn’t contain any confidential or sensitive information from your previous (or current) role such as customer or product names.

If you’re pivoting from software engineering, ideally you’ve already written documentation for features (or side projects) you’ve built. If not, now is a great time to do that. Documentation from my software engineering bootcamp capstone project was one of my initial portfolio pieces. On-call runbooks also make great writing samples as long as they are concise and clear.

Creating new content

There are many opportunities to draft new technical content just for your portfolio.

Find an open-source project and write some READMEs and basic documentation for it. Take existing technical docs and reorganize and rewrite them (just be clear about that in the writing sample, such as adding a note at the top with a link to the original source).

Document how to play tic-tac-toe

A common prompt if someone lacks a technical writing sample is having them document how to play tic-tac-toe. This sounds straightforward and can be done in a brief document, but an experienced tech writer will glean lots from how you structure and organize the doc and how clearly and succinctly you can describe such a familiar game.

Brush up on your editing skills

Editing is a key part of technical writing, whether you’re self-editing your own drafts, peer editing another technical writer, or doing more intensive editing of content drafted by engineers or other subject matter experts (SMEs).

Take some time away from your writing samples and then re-edit them again once you have fresh eyes. Look for any words that aren’t absolutely essential and cut them. Evaluate whether you’re presenting the content in the most logical order. Put the most important idea at the beginning of the sentence rather than the end.

Make sure you actually enjoy the writing and editing

If this exercise wasn’t a fairly enjoyable way to spend 5-10 hours, then technical writing probably isn’t the right choice for you and it’s much better to find that out now!

Heads down writing and editing isn’t the entire job, obviously, but it’s a big part of it. Sometimes people like the idea of writing more than the actual writing, which is totally understandable but an important signal to listen to.

Don’t be tricked into thinking tech writing is just “a less technical version of coding” or “kind of like program or product management but a bit more writing.” Tech writing isn’t just a slightly less stressful, slightly less technical version of being a software engineer. It’s an entirely different career where you’ll be evaluated on a different but overlapping skill set. You will spend A LOT of time writing as a technical writer, untangling thorny sentences, re-editing the same document 3 or 4 times, and meticulously applying a style guide.

There are many similarities to any knowledge worker/white collar job: Going to meetings to understand the problem and what needs to be done. Sitting at a laptop doing stuff (whether code or Google docs or excel sheets or .md files). And nagging people to approve and review stuff.

But that part where you’re sitting at your laptop doing stuff will be many hours of your life, so make sure it’s something you generally enjoy. Writing and coding feel different. Coding may feel more interactive and more tangible and thus much more satisfying for some people. They’re both amazing fun some of the time. But make sure it’s something you enjoy most of the time!