The 4 Must-Have Skills for New Technical Writers

Looking for a career in technical writing? This is where you start!

In my last article, I highlighted three exciting entry-level jobs for language experts looking to break into the tech industry. The most popular choice was...

Technical writing!

Great call! 🙌

Strong language skills, but no computer science background? These jobs are your entry ticket into software development

Since there is some interest in that role, today, I share the most important skills to have as an upcoming technical writer.

While senior technical writers often have a wide repertoire of skills, we all need to start somewhere. So before you learn how to use countless tools or programming languages, let’s start at the very basics.

Learn to walk first. We can run later.

Communication and Language

Surprised? Didn’t think so, either.

Language is your primary tool as a technical writer. You use it to conduct interviews with stakeholders, discuss with peers, and write documentation.

But language is more than just your tool. It is your calling card.

Just as you wouldn’t trust a bricklayer who can’t make a solid handshake, you don’t want to trust a technical writer who can't handle the nuances of clear, concise language.

If you start to have doubts, don’t worry. The eloquence I suggest doesn’t mean to start talking in Times New Roman, like a Shakespearean reincarnation.

Technical writing is all about using simple language precisely and efficiently, instead of being a walking Latin thesaurus. You need to match your language with the knowledge of the reader.

For example, take this sentence: Download the latest Chrome Browser.

Most people younger than 60 will have no problem following your request. But if you ask your 88-year-old great-grandpa the same, he will look at you, all confused, and divert with an old war story.

On the other hand, if you start explaining a Browser to your teenage child, you’ll get side-eyed.

Here are a few tips for cleaning up your language for your technical writing career:

• Use as few words as possible to explain the concept to the reader. Also, synonyms are poison in technical communication and technical writing. They introduce ambiguity, and ambiguity is the arch-enemy of any technical writer. To put it simply: Forget what you learned in school. You do not need to artificially fill up 5 pages of gibberish.

• Use short sentences.

• Build up your sentences logically, i.e. from the start to the end, or from the abstract to the concrete.

Research Techniques

While clear communication is essential in writing, it's just as important to gather the right information first—this is where your research skills come in.

As a technical writer, you will constantly research for information. The one rookie mistake I see most new technical writers make is this: They depend too much on their subject matter experts for answers.

The biggest tell of a weak researcher is asking stakeholders questions you could have Googled yourself. Don’t do that. It hurts your reputation… It hurts our reputation.

You want to set yourself up as somebody who takes away the writing tasks from your product manager, developers, etc. You aren’t doing that when you expect them to spoon-feed you everything you need to write. It is just a waste of time for anybody involved.

Here’s what great technical writers do:

1. Search for any internal documentation on the topic: Microsoft Sharepoint, Confluence, Github, or the ticket system. Find out where the teams keep their internal documentation and use this information to answer your questions before approaching anybody.

2. Haven’t found your answer? Use ChatGPT and Google! Especially, if the question is not product-related but is about a more general topic, you’ll be able to self-educate. Make sure to confirm your ChatGPT results.

3. Standards, though sometimes hard to read, are an underrated source of information. Many products are implemented according to a specific standard. Your company will have that standard available. Get a copy and study it.

4. Still not able to answer all of your questions? Now’s the time to conduct a user interview. But don’t just schedule a meeting and then make up your questions on the fly. The number one rule for interviews? Come prepared!

   1. Have your questions written down.

   2. Roughly understand the concept about which you will interview. Otherwise, you will struggle to understand the interviewee and render the interview inefficient.

   3. Document the answers. If you are in an online meeting, you can ask the interviewee if you may record the session so you can fully concentrate on listening, instead of writing down the answers. I have never met anybody who had a problem with that.

Another hard tell of a beginning technical writer is taking their research input at face value. Your stakeholders will share rather technical explanations of a feature. It is your task to convert it into something the users understand. You act as a translator, so to speak.

XML

User manuals are mostly written in XML format (Extensible Markup Language).

The main benefits of XML-based writing are:

• Consistency of documentation structure

• Consistency of layout

If you have ever written a large document in a Desktop Publishing Tool like Microsoft Word, you know how hard it is to keep structures across different documents consistent. Also, it is way too easy to mess up your layout by introducing that infamous last minor tweak.

Now imagine you work on documents that contain thousands of pages. On top of that, the document is written not by one, but 5 or 10 different technical writers.

Microsoft Word was not designed for that. It will remind you of it if you try.

Other than such layout-based tools, XML separates the content from the layout and the structure.

This way, the author only focuses on writing the content in the XML file. An XML file looks like this:

<procedure>
   <title>Cutting an Apple</title>
   <para>This section describes how to cut an apple.</para>

   <prerequisite>You have a knife at hand.</prerequisite>
   <prerequisite>You have a peeler at hand.</prerequisite>

   <instructions>
      <step>Peel the apple with your peeler.</step>
      <step>Cut the apple in half.</step>
      <step>Cut the halfs in half again.
         <stepresult>You have 4 pieces of an apple.</stepresult>
      </step>
      <step>Carve out the core of the apple.</step>
   </instructions>
</procedure>

It might seem complicated for an upcoming technical writer but you get used to using the XML elements.

You can see, there is no layout. The layout is generated using scripts. The scripts take the XML elements that you can see above and format them according to specific rules. You can transform XML into different formats, e.g. PDF, HTML, or other XML formats - at the push of a button.

On top of that, the structure of an XML file is defined by a DTD file (Document Type Definition) or Schema file. These files make sure that your documents are consistent, even when multiple writers work on them.

For instance, the DTD or Schema defines which elements are allowed. In our example: <procedure>, <title>, <para>, etc. The structure files also define how many of these elements are allowed and the order in which you can place them.

We could, e.g., specify that <prerequisite> elements must come before the <instructions> element.

A parser will check that your XML document matches the rules defined in the DTD or Schema. This strict structure keeps all documents consistent, even when written by different people.

Content Component Management Systems (CCMS)

A Content Component Management System is a powerful tool that helps you manage your content.

While not all technical writing teams can afford such tools, the concept behind content management is universal and a must-have skill for new technical writers.

Before I explain what a CCMS is, let’s look at why we need them.

There are several standards out there to standardize documentation, e.g. DITA, DocBook, or AsciiDoc. What all of them have in common: They modularize content.

Instead of writing one giant document in one file, we manage units of content, often called topics. Topics are self-contained units of information that answer specific questions, e.g. how do I install the product?

Topic-based writing emerged when hypertext-based documentation (HTML, CHM) replaced linear documentation formats (print, PDF).

Users navigate hypertext-based documentation differently than linear documents: Less power-browsing, and more use of the search function. Topic-based writing supports this approach.

More so, modularized content helps you keep better track of your documentation variants and versions. Often, you will document different variants of products, and with the products, you will have to offer variants of documentation, too.

A CCMS manages these versions and variants of your topics and helps you organize them into different documents.

A CCMS makes sure you can follow a true single-source approach. The principle is easy:

1. You write your topics in a way that makes them reusable in several documents.

2. In a CCMS, you don’t copy such topics into the documents; you reference one original topic.
   When the original topic changes, the documents that reference this topic are updated, too.

That’s efficient and helps you keep all documents more consistent and up-to-date.

Here’s a simplified depiction of how CCMS tools help you manage your content:

Examples of CCMS tools are Schema ST4, Cosima, or MadCap Flare.

Structuring Content for Your Users

I saved the most important one for last.

Even an entry-level technical writer must understand that the goal is to write for the reader, not for themselves.

You write for a specific target group.

That’s why you need to strongly emphasize the user’s needs. Understand them and learn how to structure documentation accordingly.

By the way: Setting up new document is something most technical writers rarely do. More often than not, we only maintain and extend already existing documents.

Still, the skill of setting up a document is vital for any new technical writer. It also helps you understand better how to extend and maintain existing documentation.

If you can do this properly, you are already better than several senior technical writers I’ve met.