Maintaining a portfolio

Most job searches require that technical writers produce one or more samples of their writing. Managers and other interviewers rely on such samples to determine the abilities of the applicant. Because nearly every job posting expects a writer to provide a writing sample, a tech writer on the job hunt should have one or more samples ready.

What to include in a portfolio

A portfolio consists of a set of the writer’s best samples of their work. What “best samples” means is entirely subjective on your part. When building out a portfolio, include samples of writing that:

  • you are exceptionally proud of.
  • demonstrate a particular skill.
  • validate domain knowledge in a particular area.
  • showcase your understanding of good technical writing technique.

Hiring managers and interviewers are pressed for time like anyone else. Long pieces are unlikely to be read in their entirety. Include the best sections that really showcase your skills and abilities.

You can include links to published documents you contributed to. Include disclaimers where appropriate, as content you do not own or host on your own site may change or be removed at any time.

Include a short description of each piece that talks about your process for creating it. Even for samples you create on your own, overview who you would expect to involve in creating the doc. Would you talk to product managers, engineers, QA? Would you involve reviewers or editors? Talk about your process for writing your samples.

Make sure you craft your portfolio to target the type of role(s) you want. It is perfectly okay to have multiple portfolios for different types of jobs.

  • When applying to editing roles, having before and after samples of work you edited would be beneficial.
  • If applying to information architecture roles, provide examples showing good practices for tables of contents and knowledge management.
  • For API documentation roles, the portfolio should demonstrate knowledge of HTTP request types, responses, and standards like OpenAPI.
  • For manufacturing, include design drawings.
  • When applying for senior or lead technical writer roles, include samples that show your project management and leadership skills.

What not to include in a portfolio

Never include writing that you do not have the rights to. Remember, when you write for someone else in a job, they own what you produce, not you.

If there is a sample you wrote while working, ask your employer (or whoever owns it) if you can use it. Make sure you receive explicit permission in writing from someone with the authority to give you permission to use it. Abide by any restrictions they may have, such as scrubbing sensitive information or branding.

Never include real or sensitive information about you or others. Do not include passwords, URLs, trade secrets, unreleased features, personal information, or other such items.

Avoid including long samples, as those reviewing portfolios are unlikely to read them.

Writing samples when you don’t have permission to use real work

Most employers understand that work-related materials cannot be shared. After all, they do not want you to share the work you do with them, either.

So what should you do instead? Create your own content not related to your current or past jobs.

  • Document a tool or software that you use regularly
  • Write out a “how to” for defeating the first boss of your favorite game
  • Create a “how to” for an open source tool
  • Craft a recipe in the style of the kinds of technical documents you write (or would like to write)
  • Discuss the role of style guides, including your preferences

In short, use your imagination. Consider the kind of writing you know how to do well, and include something that really showcases that style. If you want to shift to a different kind of writing, create a sample document that reflects the new direction you want to move into.

Where to host your portfolio

There are two important considerations when hosting your portfolio: - Ability to add your content - Freedom to share that content with potential employers

There are many options for hosting your content depending on how you write it.

  • Online drives like Google Drive, Microsoft OneDrive, an AWS S3 bucket, iCloud,, Dropbox, and similar are all great places. Create a folder for your files, load them up, then share the folder when the time comes.
  • A self-created website built with HTML, CSS, and/or JavaScript and hosted on a public server.
  • Wordpress website. Wordpress powers 47% of the web, or so one statistic says. There is a reason it is so widely used. If you are familiar with Wordpress or want to become familiar with it, this is a good way to build those skills. Similar tools like Squarespace or Wix are just as valid for hosting your samples.
  • A static site generator hosted on Github Pages, Netlify, or your own cloud storage. SSGs make it easy to convert mark up text into a static web site. Many documentation teams use SSGs to publish their docs. Use creating your portfolio to learn docs-as-code publishing steps and tools like markdown, Hugo, Mkdocs, Git, and so many more.
  • Create one PDF file of your samples that you can provide when asked.

You can also have printed samples ready to hand over for in-person interviews. However, those are more difficult to share among all the members of an interviewing team.

Other portfolio considerations

Your resume is the first piece of your portfolio any interviewer sees. Don’t neglect it.

How you create your portfolio is itself part of your portfolio. Consider writing out why you created your portfolio the way you did, what steps you took to complete it, and any problems you solved along the way. Then include that as one of your writing samples. Be sure to include any skills you learn or tools you use along the way on your resume!

Your portfolio should represent you at your best. Be sure to carefully comb through your samples for grammar and spelling errors and clean them up.

For some positions, the format and storage locations of your portfolio make a difference. But for most hiring managers, those details do not matter. Don’t stress about it.

You can make building your portfolio a learning opportunity, but don’t make building it a stumbling block. It is more important to have a portfolio than to have a learning opportunity from creating it. If you’re struggling with a particular way to create your portfolio, try a different means. Wordpress is perfectly fine if you can’t get Hugo to build the way you want it to. Word docs are perfectly fine if you have no interest in learning Markdown or DITA. It’s your portfolio. You get to decide.

Ask for help and portfolio reviews from the Write the Docs community. The #career-advice channel in Slack is a great place to ask.

Portfolio examples

A list of portfolio examples from Write the Docs folks who have agreed to share theirs here:

Other resources