So, you are a technical writer looking for work, and you need to submit some writing samples to get to the next stage of the hiring process. What is it that hiring managers are looking for, what can you provide, and what can you plan to have ready for next time?
What sells you
Every hiring manager is getting multiple applicants and reviewing several sets of documentation. Your goal as a candidate is to stand out by being topical, considerate, and compelling.
Look up what kind of industry you're applying to and see if you can match that to any of your existing samples. If you're applying to do software security writing, find the samples where you describe end-to-end encryption or private-public key theory. If you don't have any samples that are a real match, get as close as you can and then explain in the cover letter or a separate sample explanation document. If you are relatively new in your career, you may need to write something just for this interview. That's OK. Anything you write now will go in your portfolio to pull out and fix up later.
You don't want to drop 600 pages of documentation on this poor manager who is reading documents from many people already. Pick two- to four-page extracts of documents that you are proud of. Make sure you're clear that there is more to the document and you're just presenting a sample for consideration.
Giving people the files in a usable format will also help. PDF is almost always acceptable. Don't count on anyone having a copy of FrameMaker, DocToHelp, or Madcap Flare sitting around. Whatever format you choose has to be portable and immune to version changes for at least the next couple years. Don't password lock the files, because that reduces people's ability to pass them around and compare you to other candidates. You'd be surprised at how many support and QA leads end up helping a developer manager make decisions.
I usually ask how many samples people want, but if they don't tell you, plan on a minimum of three samples.
Every hiring manager is asking themselves, "Can this person solve my problem?" It's easiest to get hired if you answer that unspoken question. AskaManager.org suggests that you figure out what the problem confronting your interviewer is and go in prepared to tell them how you'll solve it. Documentation hiring falls into that category, but often the problem is a messy intersection of tools, legacy documentation, and office politics.
The way to be compelling is to make it easy for them to visualize how your writing, your research style, and your existing background is going to be a useful addition to the team.
Don't do this
Don't submit anything with errors. Get someone else to edit it for you, even though yes, you're a professional. Even professionals miss things sometimes.
Don't submit anything you don't have permission to do so. This means that if it's confidential, it can't be part of your portfolio. If the NDA that you signed at the beginning of your last job prohibits it, you may not be able to use anything from that job. Obfuscating the identifying details of a document is a necessary but not a sufficient step if you're going to use anything that you wrote for someone else. Basically, if it's work-for-hire, you're going to have to get written permission before you can claim it, which is sometimes a downer, but that's how the process works. If you leave a job on good terms, the exit interview is a good time to ask if you can take some samples with you. You may need to demonstrate how you would obfuscate identifying company information.
Don't plagiarize anyone. You'd think this would be obvious, but I still need to say it. Hiring managers can use Google and term paper matching as well as anyone else. If you get caught, not only will you not get the job, you'll get an ugly reputation in your area, whether that's physical or industry. People will gossip about it for YEARS.
Don't claim sole ownership of something you wrote as a team. You need to identify what you wrote alone and what was a collaboration. It's useful to have documents that were collaborations, just be clear on which part you wrote.
Depending on your level of experience, you'll have different sets of sample documentation available. Your topic will matter less than the breadth of your experience. Here are some types of documents that you may want to work on having samples for:
- Conceptual (maybe with a drawing)
- Release notes
- Thoughtful index
- API documentation (You can do this as an open source contribution. I recommend SwaggerHub as a tool.)
Remember that you don't need to have the full document written, you're only going to provide a couple pages of each. You do want to make sure that the conceptual document is a coherent thought, not just the middle.
It would be great if you have a variety of technologies in your samples; for example, one from a game, one from 3D printing, one from security, etc. Having a range of technologies is like painting a house for sale in a neutral color. It allows potential employers to imagine their technologies in your writing and proves that you're versatile enough to take on their product. If you have something from the company's particular industry, this sample should certainly be into the mix.
Don't copy this template exactly, because it's rude to copy.
Dear Hiring Manager,
Thank you for asking me for samples. I'm excited to share my experiences with you. I've included three samples for you.
The API document is a sample project that I did for the Quill open source project. I wanted to document the way that external developers could connect to the data source and use it for their own purposes. They did have a publicly available API at www.sample.com/api, but it didn't have any documentation or usage examples. You can also see the sample in a dynamic way at this GitHub address: github/me/quillapi.
The second sample is a conceptual explanation of public/private key exchange. I was inspired by this YouTube video (YouTube link) about mixing paints as a metaphor, but I rewrote it to be about mixing filtered lights so I could incorporate the idea of a diffuser as well as hashing.
These release notes were a team project. The developers wrote the original fix information, and I polished the language and wrote the new features section. The other writer on my team wrote the installation instructions.
I hope these examples give you a feeling for my breadth of experience. If you would like to see any other type of document, or you would like to discuss any of these in more depth, please feel free to contact me.
I also have some techniques that I've used productively that may be useful, although they may possibly be inappropriate for someone applying to be a junior writer on a team. I have been a solo writer for most of my career, so I need to not only to prove my competence at writing but also why an organization needs a technical writer at all, and me in particular.
Conduct a documentation audit
This only works if the organization has existing public documentation.
Review what they have and note gaps or outdated data. Write up a tidy table of contents that notes all the things that need to be added, updated, or removed. For example, you can encourage them to remove their product's support of browsers that are no longer supported. I don't suggest spending more than about three hours on this—after all, you're working on spec for them.
The tricky part of presenting this is finding out their relationship with the person who did the previous documentation. Sometimes it was either a frustrated developer or a much-missed previous writer. In that case, you want to be clear that what they have is a very solid foundation, and you would just suggest working on these particular areas. However, if it's clear that they feel they were burned by the previous writer, you can say, "Well, in my professional opinion, you really need a Quick Start guide, and I'm happy to write one for you." Never trash the person who did the documentation, but do point out where you can improve things for the organization.
Show a before-and-after document
This one can be super-compelling if you can get permission to use both documents. I take a sample of a spec, or undocumented API, or terrible MAN page, and present it side-by-side with the work that I did. I'm prepared to talk about why I made this or that design or description choice, why I left something out or included new information, how I researched the new information, what the user response was like. Doing a before and after really lets people see how transformative a writer can be, and how we can take something mostly usable and turn it into something clear and lucid that helps people get their jobs done.
This is the riskiest option, but it can pay off nicely. You have to have access to public documents, and they have to be bad enough that you will make a notable difference fixing them. You can also independently document integrations with what your target company is selling. Once you have that done, you combine the two methods above to show what you can do with what they have to offer. Again, you don't want to spend a bunch of time doing this, because no one is paying you. Also, as an honestly check, you can send it in a PDF that prevents copying. If anyone complains to you about that, you can ask why they wanted to extract what you wrote for them. But that is only for the most ambitious and suspicious people to try.
About writing tests
You'll frequently get asked to take a writing test. Ideally, you would get compensated for your labor, but I have yet to have that happen. Instead, it's unpaid time, just like interview time.
Ethical companies will do the following:
- Explain how long they expect you to work on the sample.
- Give you adequate lead time to work around other commitments you have.
- Only ask you to work on something that doesn't directly benefit them.
If a company asks for the following, you may want to push back if it:
- Asks you to write something that it could use in its documentation right now.
- Gives you a very tight deadline to return the test, as if you didn't have a job and commitments.
- Makes vague suggestions or none at all as to how long you should work on something.
- Requests you do something unethical, like rebranding copyrighted material.
Go get 'em, Tiger!
Technical writing is an amazing career, and you get to learn so much about products and people. I absolutely encourage you to keep pursuing it. However, the same warnings that we give to developers apply here:
- Choose a work environment where it seems you will be respected.
- Keep in mind that work is not a family, nor your friends, and attempts to make it seem that way will tip the power balance.
- You're interviewing them as much as they are interviewing you.
- The products that we make do make a difference in the world, but that difference is not always good. Decide for yourself if you feel that your work is an ethical fit for you.
- This is not going to be your forever-job. Make sure you read and understand the contracts that you sign and what will happen if and when you leave.
- Don't take the first number they offer for salary—that's an opening gambit. Practice saying "I was hoping for a bit more" with a friend until you can do it without freaking out.
- If you go to work for a new-ish company, ask how they're funded and how much longer the money may last. In my observation, the technical writer is one of the first positions to get cut when a company is in trouble.
Special for writers:
- Your work is no less valuable than coding people. Many companies will attempt to pay you less, but your industry knowledge is just as valuable, and you manipulate symbols to create meaning and action the same as they do.
- It's OK to want to be a generalist and write everything a company puts out, and it's also OK to be a specialist and only do documentation, or only API documentation. Just know what you're comfortable with because marketing writing is a different and equally difficult specialty.
- When you do work-for-hire, you don't ever own that work, and you probably don't get to sign it. That's a real shift for some people who have always gotten credit before.
- If you do think the work will either be public or you will be able to use it, I suggest using your name or some other identifier as sample data so that you can confidently point to something you wrote. It also will show you when the document gets updated and it's not "yours" anymore.
- Be ethical and careful in your use of data. Try to make sure you have a range of people represented in examples—people of all genders, people with names from different language groups, people who may be under-represented. Use an industry-standard style guide to make sure your samples are as universal and accessible as possible.
Additional tips to add? Leave a comment or tweet to us @opensourceway.