Building a tech writing portfolio that will win you new clients

Around February 2012, I was headed into a final interview for a technical writing role at an energy company. I had no prior experience of working in the energy industry, so I figured that would be mentioned at some point in the interview. 

Surprisingly, the interview went pretty well and towards the end of the interview, when the interviewers asked to see samples of my previous work, I handed them a CD where I had meticulously curated some of my previous work samples, with redacted portions to protect client sensitive information. The samples covered 2-3 of my previous projects, just to give enough understanding of the range of work that I had done outside the energy industry.

24 hours later, I got a call that I had got the role, and a large portion of that decision came down to the work samples presented on the CD. The feedback was that they were impressed with the quality of work presented and the idea of the CD itself!

Point is, it only added credence to the fact that a tech writing portfolio is worth its weight in gold. A good portfolio adds a final flourish to your technical writing experience.

This blog post covers some ideas on building a tech writing portfolio, along with my recent personal experience of building a portfolio using a combination of Markdown, Git, and a Static Site Generator.

Building a portfolio

There are a few ways to approach building a portfolio.

• You can choose to print out some of your best work and carry a folder to interviews to walk interviewers through these samples. 
  • The advantage of this is that you can carry samples of work that is not publically available, but directly relevant to the role you are applying for. 
  • A word of caution though: to protect client sensitive and any copyrighted/IP material, you should redact relevant parts of these samples.
• You can choose to have a shareable document that curates some of the work you may have done and is more generally available publically online. 
  • One advantage of this is that it allows you to adapt or modify your samples to the role requirements. 
  • You can also point interviewers to something available online for easy access.
• You can have a dedicated website that highlights your writing, along with a raft of other skills directly, such as information architecture, navigation, content organisation and understanding of design. 
  • The advantage of this is that it provides a coherent structure of your writing experience and provides a glimpse into your design skills. 
  • One of the drawbacks of this is that you have to invest time to create, curate and maintain this site consistently, to keep up with your growing experience.

What should go in a portfolio

There are quite a few resources already on the internet that covers this in great detail:

• Building a technical writing portfolio on Medium
• How to build a technical writing portfolio on ClickHelp
• Put together a portfolio on I'd Rather Be Writing

As a technical writer, I would be keen on putting on best foot forward, so these things would definitely be top of my list to include:

• 5-6 of my best work samples, across a range of documentation types such as user guides, online help, process/work instructions, API and developer documentation etc.
• Background, context and your approach in creating the documentation and the tools used to create the docs
• Summary of any open source or freelancing projects worked on
• Any presentations, articles or blog posts delivered and publicly accessible.

My current portfolio

Sometime last year, I started working on updating my portfolio from a shareable document with a list of links to a dedicated website. The purpose of this was two-fold:

• Firstly, it allowed me to apply structure to a growing list of work samples
• Secondly, it gave me an opportunity to learn, pick up and polish my skills on a new documentation toolchain - Hugo static site generator (using Markdown for creating content), Git repos (for storing the code and outputs) and GitHub for publishing my portfolio. 

As I started building my portfolio, I also realised that this was an excellent opportunity to use some content strategy concepts such as information architecture, navigation, substance and structure to demonstrate my skills. 

Using Hugo, Git and Github

I had previous experience working with Markdown across some of my earlier projects, but I was keen on trying out a static site generator for this exercise. I settled on Hugo as my choice. Following Hugo’s documentation, I chose the Hugo Resume theme and played around with it. 

Some of the initial hurdles revolved around:

• Setting up the Markdown editor (I usually work with Atom), 
• Getting my head around the concept of archetypes (essentially, templates), and 
• Growing comfortable with the self executing nature of Hugo engine as you create content for the site. 

I also created separate repositories on GitHub; one to store my code and docs, and the other to store the output files.

Once the environment was set up, I drew up a plan of content I wanted to be included and gathered the relevant resources (images, links etc) for the site. 

Working through Hugo’s documentation, I managed to create a draft of the portfolio I was relatively happy with. The next step was to push these changes to the GitHub repositories and host it on GitHub pages. 

(To be honest, I had initially planned to host this on Netlify, but I felt safe in the GitHub environment, so decided to go with this).

I pushed a draft to GitHub pages and the portfolio was effectively ready. 

Reviews and fine-tuning

No piece of technical documentation is ever ready without a review. Going with this adage, I decided to test out this portfolio by getting a few fellow technical writers from my network to review this. I deliberately chose to ask a cross section of tech writers, including technical writing managers to review this from different perspectives. 

Once they had reviewed this and provided some really constructive feedback, I was able to fine tune the portfolio content and share it confidently with a larger audience.

Reviews, often the useful ones, are often so overlooked in the technical documentation space. Having another set of eyes look at the portfolio via different lenses has made the portfolio more consistent and less error prone. 

Ongoing maintenance

Like a lot of technical documentation out there, a portfolio is never 100% complete. There will be numerous instances when you will be adding to or updating this site. Ongoing maintenance should also figure in your plans if you wish to keep maintaining an online version of your portfolio.

Final remarks

Working on the portfolio was a great experience, especially trying to learn the inner mechanisms of doc tooling and setting up a doc workflow that works. 

• A portfolio is a great way to showcase not only your skills, experience and the best of your work, but also an opportunity to demonstrate your thought process and outcomes from the experience. 
• Keep it simple. The idea of a tech writing portfolio is to demonstrate your writing chops and how you approach different documentation projects.
• Do not underestimate the importance of showcasing your open source achievements. These hold a considerable currency in software projects than you imagine.