Here be dragons

How to become a Technical Writer?

I have been receiving messages from people asking how to become a technical writer, which tools to use, which technologies are important, and what matters most. It’s difficult to specify tools because each place, each project, and each company has its own. What you should focus on the most is HOW to do it (how to write clearly, concisely, and assertively; how to structure your text; and, most importantly, HOW to test your text).

First of all, technical writing is about making people understand what a program does, a system does and making people able to use it, whether or not they are programmers (HCI → Human computer interaction).

And interaction designer is focused largely on how best to create efficient and effective interactions between users and interface. These interactions could happen within screens, between screens, or even beyond the screen. As an interaction designer, you may sketch out screen-based interactions or even interactions beyond the screen with a pencil or on a whiteboard. And then iterate those screens and interactions based on real-time input from a team of stakeholders. You may also sketch out screens and create static mock-ups by using software. You may create interactive wire frames or clickable prototypes that let stakeholders or clients click through and experience a basic level of interactivity. Whether static mock-ups or interactive wire frames when designing for the web, you'll be focusing on screen elements that could include where text will go, what buttons and functionality will be present, how menus will be placed, and how headers and footers will be structured. As you review information architecture jobs in fact, you'll find that most are focused on the creation of web and perhaps mobile resources, often websites specifically.

(...)

You would attempt to learn through this research how users naturally group those terms or topics together. The usability test would involve having users do actual tasks on the website, where they're asked to get from point A to point B in order to provide a baseline understanding about the effectiveness of the existing site structure. You may also validate design decisions later on with these same methods or perhaps with a tree study using a tool such as Treejack, where users are presented essentially with a series of menus that they can dive into to see how they perceive site structure. You may also do a first click analysis where you ask users to do a task on a static mock-up and record the first click that users make.

(...)

The technical writer is charged with the task of making sure that important technical information is understood by the intended audience groups. The technical writer functions as a very specific kind of content writer. Someone who can understand enough from developers or engineers about the technical ins and outs of the website application or product, and then translate that understanding from the more technical source into user-friendly explanations. The technical information may come in the form of screen-based help, or it could be hard copy or electronic documentation that is used to help consumers understand more about software or physical products. While some of what you produce as a technical writer could be long and descriptive. It could also include just-in-time help texts such as error messages. You would need to make sure that users understand errors and have enough information to successfully recover. In addition, creating elements such as labels and tool tips may also be part of your job. Like an information designer, you may also produce more than just words. It may integrate screenshots, illustrations, or even videos as well.

(...)

The guide briefly describes what tasks insured people can complete in each section of the member portal. They don't have to complete the tasks to use the portal. But they might want to use those functions eventually. For example, you'll see this StayHealthy Online Programs section. Users might use this feature of the portal but it isn't essential to getting started. The guide provides information on how to do it but it doesn't compel the user to complete that task. Now, you may be wondering weather it's okay to blend procedural information, steps that must be followed in a sequence, with conceptual information, such as descriptions of tasks or features. Can you write a quick-start guide that includes both must and may? The answer is yes but you have to do it carefully or your user won't be able to quickly see the overall purpose of your guide. Here are two tips for presenting the two types of information in one quick-start guide. Create distinct sections of the guide for the procedural and the conceptual information. Let's look back at the Orange Valley Health Member Portal guide for an example. This example of the member portal now contains both types of information. We have a lot of may information here but also some must instructions for how to create an account. You'll really want to make it clear that the sections are distinct. So we could make them have two different background colors, and put some buffer space between the text. Another way you could combine the information is to provide the conceptual information, then give the procedural steps that support each concept. If you organize your quick-start guide this way, the conceptual information leads the way and the procedural information or sequence of steps supports it. So when you are writing a quick-start guide, must or may is the question. Am I explaining what users must do or what they may do? And sometimes, the right answer is both.

(...)

It's better to be useful than pretty is a great saying when you're incorporating visuals into your quick start guide. Sure, you want the guide to be attractive, but any visual you add, whether it's a drawing, flow chart, or screenshot, must be useful to your user. Space is tight, and your readers need to use your guide to understand or do something they care about. A well written quick start guide combines written explanations and useful visuals to help people understand how to get started with your product, process, or tool.

Be consistent. Use the same markup each time you want the user to see a similar thing. For example, if you're using a red arrow on the first screenshot to point to the item the user should click the complete the step, don't switch to a red circle on the second screenshot. That would just be confusing.

Use numbers to indicate a series of steps on one screenshot or a series of options. No need to go screenshot crazy. Sometimes one screenshot will serve to illustrate several steps. If this is the case, just number the items in the screenshot you want the user to notice. If your screenshot has a lot of information and text in it already, you may want to pull the annotations off of it and put them to the top side or bottom.

Use thin lines to connect the annotations to the place they relate to on the screenshot. Visuals that are merely decorative are of no help. So if, for example, you were writing a quick start guide that explains what happens during a grant application process, it would be really lame to decorate it with visuals like these.

Here are two reliable ways to refer to your users in your guide. Use second person pronouns you, your or yours. For example, instead of writing "The user should click Protected Account to view "all the status information on each registrant." You should use the pronoun you, write this instead. "You should click Protected Account to view "all the status information on each registrant." Use the imperative mood, which is a command form of the verb. When you use the imperative mood, you imply but don't write the word you. Here's the same instruction written in the imperative. "Click Protected Account to view all the status information "on each registrant.”

Tips

Ask a subject matter expert to review your quickstart guide with those in mind:

It's always better to start a quick start guide (or a guide) with a verb for the action that'll be performed.

The present tense is always preferable for starting actions/indications. This makes the text clearer and the steps more precise for the reader. Important information should always begin the sentence, so that it draws the reader's attention more than the end.

Always put common terms next to technical terms, this makes them easier to read. Always indicate that this is an explanation of the technical term used in the document. It's good to create a short glossary too.

Translated with DeepL.com (free version)