The Not Boring Tech Writer: Using Your Detective Skills as a Technical Writer

Catherine Heath | September 10, 2019

This is our write-up of The Not Boring Tech Writer podcast episode called Using Your Detective Skills as a Technical Writer. The podcast is produced by Jacob Moses and sponsored by KnowledgeOwl. 

As technical writers, we often wear many different hats within our organization. To name just a few, we write documentation that teaches people how to use a product; we test new features to ensure they’re working properly; we write marketing copy that encourages people to research a product. 

We wear yet another hat that you perhaps haven’t yet considered, but is essential to the technical writers’ skill set. This is called the detective hat and is presented by Jamie Roddy on this episode of the podcast.

Jamie is a Manager of Technical Communicators and she leads a team of global technical communicators for a software company. From her love of detective shows, Jamie has discovered that the detective and the technical writer have a lot in common. 

Jamie shares how you can use your detective skills more effectively as a technical writer, including:

  • Which detective skills are most useful for technical writers
  • How to ramp up those skills
  • How detective skills can help you transition into other fields within a software company

Jamie’s background

“I got into technical writing when I was a little kid,” says Jamie, referring to her She has love of writing and reading. Jamie got her Bachelors in English Literature and then she completed her Masters in technical writing at the University of North Texas. At the time, her Masters was a new program, but now the university offers Bachelor degrees in technical writing too. 

While taking country drives with her teenage son, Jamie listens to a radio program called Guy Noir: Radio Private Eye in which Guy Noir solves crimes. While listening to this program, Jamie decided that Guy sounded like a technical writer. 

This led her to discover that many other detectives are very much like technical writers, since both roles are required to research, investigate, and interview during the course of their work. 

How technical writers are like detectives

Now we’ll go into a little more detail about how much crossover there is between detectives and technical writers. Just like technical writers, detectives need: 

  • Effective communication skills
  • Ability to do deep research
  • Organizational skills
  • Patience
  • Ethical behavior
  • Attention to detail

So there is a deep connection between being a tech writer and being a detective. Jamie has made this connection also to show how being a tech writer is not at all boring. Although tech writers don’t solve murder mysteries like detectives, many of the skills still overlap and the work still very much involves unravelling mysteries. 

In the software industry, you’re usually developing a product from scratch. Somebody answers a need in the market with their product, and you go from having very little to work on to building interfaces through code. A detective typically also knows very little about what has happened when solving a new crime, just like a technical writer documenting a software product. 

Using detective skills in your documentation

In the course the technical writer job role, detective skills play an extremely important role. You begin with broad general ideas and work hard to build a concise document, which is a lot like solving a crime. First of all, you use different tools and research the many key players who were involved in building the product. It often takes several attempts of talking to different people before you can find the right developer to explain what a feature does. 

The documentation lifecycle is similar to the software development cycle. Documentation is creating educational content while development is creating a product. Both require detective skills to ask the right questions to the appropriate people, and being persistent when you don’t get the answers you’re looking for right away. This is just like a detective would be expected to behave. 

Often, multiple people will give you a different right answer in order to help you build a full picture of your documentation. For example, developers and usability managers will have different answers for you. Detective-like questions go far beyond finding yes or no answers, especially the ones we ask our users. In product development, it all starts with a lot of questions before honing in on the similarities of what other folks have been talking about. 

Retracing user steps

Jacob also talked about using your detective skills to retrace the steps that users said they took, in order to find out if these are actually the steps that users want to take. You need to have a feedback loop with your users, such as a feedback widget on your documentation. This keeps the channel of communication open.

It’s especially important to focus on continually iterating your documentation. You can spend a long time creating your online help, but then the help desk will still tell you they can’t find the answer in your documentation. This can be disheartening, but there’s always the possibility that you don’t know what you don’t know. The answer is more testing and alignment with your users. Remember that your documentation will never be perfect. 

Being patient as a technical writer

This detective work requires the need to be very patient. You can’t expect to get started right away, as you need to get to know the team you’re working with before you can write effective documentation. The people who you need to talk in order to find answers will be constantly changing, and so therefore do your job specifications. 

Sometimes, you start writing documentation before you even have a finished product. Often, companies will have many more developers than technical writers which means they produce code very fast. You then need to document this new code, going through the same process outlined before. You also have to be patient with developers going through the development cycle who have different priorities, and wait for people to get back to you. 

Honing your skills

“The number one technical writer detective skill is research,” says Jamie. It’s important to do a lot of legwork for the documentation and it’s no good cutting corners. Even if your product User Interface isn’t ready, you can start looking at wireframes, for example. Follow the clues before you start approaching actual staff members, who are all very busy. The key is being prepared before talking to people. 

Organizational skills are also crucial. It’s not just about writing content on the page. Jamie has to document multiple products simultaneously so she needs the right tools to help her organize her actual work. 

Jamie also talks about understanding human behavior and psychology in order to know what the user wants to get out of the product, and to help you formulate your content in a way that can best reach your audience. Adult Learning Theory by Malcom Shepherd Knowles can be very useful if you’re producing training guides. This is a learning theory that explains how adults learn differently to children – for example, they tend to be more self-directed and ready to learn. 

Starting out as a detective / technical writer

“If you’re a new technical writer, I encourage you to know your value,” says Jamie. Developers are probably glad that you’re there since technical writers are the link between the product and the end user. Your role is very important. If you can also understand the value of developers and use some of their shared language then this can also make your job easier. This may even involve going so far as to learn some of the programming languages that your developers are using. 

It may be daunting to learn software development skills, but this approach helps create more mutual respect between technical writers and developers. Better collaboration between technical writers and developers is the way forwards in the software development industry. 

All this effort is worth the trouble. Developing better detective skills can open you up to more positions in your company. For example, Jamie knows technical writers who have transitioned to project management or learning development. So better detective skills help you grow laterally as a professional within tech comm. 

“Find what you’re passionate about and do that,” says Jamie. Even though we all have the core skills of being excellent writers, there are many opportunities out there to take advantage of. As we mentioned earlier, being a successful technical writer requires wearing many hats, and it can be helpful to think about being a detective in order to inspire you to develop different skills. Although you may not be solving crimes, helping users to be more successful with software products is still a worthwhile goal. 

Listen to Jacob’s podcast in full, or check out our previous write-up on how newcomers to the industry can transition into technical writing


About the author
Catherine Heath
Catherine Heath

Community builder at KnowledgeOwl. Blogs. Copy. Documentation. Freelance content writer for creative and ethical companies. Contributing to open source and teaching technical tools.

Catherine blogs on her personal websites Away With Words and Awkward Writer. She runs the Write the Docs Northwest meetup group. 

On the go? Bookmark this article for later with Ctlr + D
Subscribe and get notified as new articles arrive
(No spam, pinky promise)