The Top Three Challenges Faced by Tech Writers and How to Solve Them

Whether you call yourself an Information Architect, Content Specialist, Instructional Designer, Freelance Writer or an Engineer of the Written Word, if you create content on a technical subject then there are certain common challenges that seem to come up again and again. When it comes to drafting your technical documentation, it’s important that you’re able to address those challenges head on.

So, what are the challenges faced by a technical writer? While many, here are my top three:

1. Getting Information from Subject Matter Experts

A major challenge that many writers face is how they get and support the technical information they’re communicating. Who you need to extract information from may vary wildly depending on your industry and/or product. However, whether dealing with a software engineer, hardware engineer, design scientist, research scientist, or head dogcatcher, almost everyone feels pressure from schedules. This means that my rule 1 for dealing with SMEs (subject matter experts) is to be respectful of their time.

I have four suggestions that can show your SME that you value their time, making them more likely to participate and give you some of that precious resource.

Do Not Send Questions via Email

I have found over the years that SMEs find email requests to be annoying. The SME may have the information that you desperately need, but they are not the professional tech writer that you are. Writing, even in the form of an email, may put them off. It is also very easy for an SME to overlook an email, or even to forget to respond to it later.

I have had my best success scheduling live discussions with SMEs—that could be face to face, video chat, or even just a phone call. The meeting has a defined start time and a defined stop time (and stick to that stop time) so the SME knows how to adjust their calendar to help you.

Prepare in Advance of the Meeting

The worst thing you can do as a tech writer is to show up at your meeting and ask, “So, tell me everything about Product X” or “What do I need to know about Product X”. If you’re offering technical writing services to a business, you may get an SME that immediately starts rambling with technical data that is way too deep for what you need or the opposite, the SME may find such an open-ended question overwhelming and not even know where to start.

You need to guide the conversation and set the SME up for success. Be prepared with some easy to answer “icebreaker” questions. Put yourself in the shoes of one who will be reading what you are ultimately tasked to write about, what information do you think they will need? You are not the subject expert, but you should be able to at least get close.

Use these points to draft interview questions for your SME. “Ms./Mr. SME, from your point of view, what are the key three or four items that a customer needs to know about this new product?” “Are there any prerequisites that a customer will need before working with our new product?”

Try to prepare at least a handful of these questions to get your SME talking. After your icebreaker questions, the rest of the conversation can be less formal.

Ask Your SME for Existing Written Assets

Something else I have found over the years that SMEs can be sensitive about is having to answer the same questions over and over. One way to help avoid that is to ask the SME if there are any written resources that you should be looking at.

Quite often an SME is happy to share engineering memos, or PDDs (Product Description Documents), slide decks from presentations, or other internal writings that you may not have been aware of. It can be a bit of work, but great information can be extracted from such existing documents. Then finally…

Thank Your SME

A week or two after your SME interview, it never hurts to send a quick thank you message. This one is fine as an email. The goal is to make sure that the SME knows that their time and help was appreciated.

There are many more techniques for improving your SME interactions, but those four should go a long way.  For more information on working with SME resources do not miss our MadWorld 2021 conference where Ryan Nicholson from Bullhorn will be presenting “Managing Your Feedback and Spending Less Time Hunting Down SMEs.”

2. How Do I Keep My Topics Consistent?

Have you ever seen technical documentation where different procedures just do not seem to follow the same look and feel? A system where reference pages were obviously written by different authors?

There are many reasons that inconsistency can happen, however there are some standard practices that will help you to keep everything looking professional while creating a technical document.

Have a Style Guide

If your corporate decisions about documentation are not set to paper (or an electronic equivalent thereof) then it will be difficult to ensure consistency. Your style guide should include information about content authoring techniques such as avoiding passive voice, your team’s decision on the use of the Oxford comma, and any other grammatical rules to follow.

Your style guide should also include guidelines for establishing corporate look and feel. What fonts to use, what text sizes, where and when color should be used. Corporate and product logo usage guidelines should also be included. Having a proper style guide will provide a common location where any author can look up the details that they need to ensure that what they write is consistent with all the other members of the team.

Create Your Own Topic Templates

I am often amazed when I visit customers that have been using MadCap Flare for years and yet they are still creating topics from the generic  “NewTopic.htm” template that shipped with Flare. The topic templates that ship with Flare are intended to help new users and to provide training value, however, if you are still using the MadCap Software provided templates after a month or two of using Flare then you are missing out on a powerful tool.

Use Flare to create your own custom topic templates and never use the “factory” templates again. There is a bit of strategy to this though. I suggest doing a content audit of your existing documentation and determining just how many different topic types that you will need. In many cases three or four will suffice.

A procedure or task type of topic, an overview type of topic, a look-up or reference type of topic, perhaps a training topic. Once you have finished your content audit and you know how many different types of topics that you will need, then use Flare to create an example of each of those topic types. Include all headings and subheadings. Apply all the necessary styles. Even provide instructional notes such as “Replace this text with the topic summary” under the various headings and subheadings.

The key is that when you go to save go to the File menu, Save, and Save as Template. Create a topic template like this for each of your topic types. Now, when anybody on the team needs to write a new procedure or a new overview topic they can start from your custom template, and it becomes as easy as filling out a form. This will pay huge dividends in consistency.

Leverage Your New Custom Templates into Contributor Templates

In some cases, you may have SMEs writing full topics for you. This process can be streamlined by saving an additional template out of Flare, a Contribution Template.

This is a special template that can be shared with your SME and they can use another of the applications available, MadCap Contributor, and they can author topics directly using the Contribution Template that you shared with them. In this way they are creating native Flare topics using a nearly identical template to what you would use and bypassing any need for imports or file conversions. This can be another huge step toward ensuring consistency.

Cascading Style Sheets Are Your Friend

Too much CSS may seem like a “dark art” practiced by special people with years of training, however it isn’t nearly that difficult. The key principle of CSS is the separation of content from formatting. In other words, we want to keep all formatting (fonts, sizes, colors, etc.) out of the topics. Instead, we want to name areas of the topic, this is a “note”, this is an “h1”, this area is a “tip”. Then the topic links to the style sheet file and it is there that we control what a note, tip, or heading should look like.

Since the same style sheet is linked to all topics it is a key tool for helping to ensure a consistent look and feel. If we need to change the look of a “note” then making that change in the style sheet file will update every “note” in every topic in my entire Flare project. Now THAT is consistency! If you find CSS intimidating then I have a resource for you. Last year I started a webinar series on “Creating a Modern Documentation Portal” and the first episodes cover the fundamentals of using CSS. That webinar recording can be found here.

3. My Employer Does Not Value Me

Ouch! That may sound harsh, but I have heard this, or similar phrases, many times over the years. The challenge usually is not that the company does not value the technical writing team, they just do not understand us and what we do, and in all honesty, we tend not to communicate it well. How can that be! After all, we are professional communicators! Yes, but we are good at taking complex and technical subjects, distilling them down to their core essence, and then passing that information along. What we tend to not be good at is communicating costs, cost-benefits, resource allocations, and all of that stuff handled by accounting or sales types. Most writers do not like communication about the “M” word – money.

If we can stretch a little, and communicate more about financials, then we have a much better chance of being heard. As an example, perhaps you are currently using an out-of-date computer that was a hand-me-down from one of the engineers. How powerful is it to casually mention to your supervisor that a new computer would be nice. We are simply trying to be polite, but it understates the benefit to the organization that a new computer would provide.

On the other hand, if we just do a bit of research and formalize our request in writing with supporting data then we are much more likely to get the upgrade that we need. How much more powerful is, “Currently using 9-year-old hardware that is underpowered for required tasks. Documentation builds currently take X hours per week of lost productivity.

With more modern hardware, time for documentation builds can be reduced by 80% gaining X hours of additional productivity per week.” When you put it that way, the company is losing money every day that they do not upgrade your computer, and they need to know that. We also need to communicate the value proposition in a way that they can understand.

Summary

I’m sure that there are more challenges of being a technical content writer than you can think of, but this was a quick list of suggestions and best practices to address three of the challenges that I have been hearing from customers for many years.