Writing is not just the technical act of your fingers on the keyboard. Writing is living.

Melissa Marr

writer, freelance editor

The statement above highlights that a career in the sphere of technical communication is a job by choice, not by chance. One should have clear understanding what it means to be a technical writer before even considering such a position. Whether you are a professional or a novice in the field, you will find this article rather insightful, since it sheds new light on the quite familiar topic.

Let’s face it, there exists a bunch of myths about technical writers which are the subject of great controversy nowadays. The vast majority of people misunderstand the essence of this job. Tom Johnson, a technical writer at Amazon Lab126, has debunked several common myths about technical writing. Learn more about it in his article “14 Widespread Myths about Technical Writing”.

This blog post discusses the following issues:

  • Role of technical communication in business and industry
  • Top challenges in technical communication
  • Great tools to overcome top technical writer challenges

Role of technical communication in business and industry

Do you, by any chance, know that technical writing traces its roots to Geoffrey Chaucer? He is the one who wrote the first technical document in English about the astrolabe, a navigational instrument. Fantastic, isn’t it? That was, just imagine, the early fourteenth century.

Another staggering example of technical communication which you probably have never heard of is Charles Darwin’s famous work on evolution “The Origin of Species”. The golden age, however, began after the World War II with the advent of the computer. In fact, it was Joseph D. Chapline who published the first computational technical document, an instruction manual for the BINAC computer.

So, as you might have understood the role of the technical communication – whether it is a hand-written, printed or electronic document – consists in facilitating user’s understanding and bridging the communication gap between the developers and the end-users.

Technical writing is becoming a highly sought after profession worldwide, especially in the IT industry. Lindsey Robbins, a technical writer at Blackbaud, claims that technical communication (also referred to as technical writing) is the conversation between the user and the technical writer. In other words, the technical writer must anticipate the questions a user would ask about the software. Technical writers serve the role of mediators between the developers and the end-users. Their main task is to create effective technical documentation in order to add value to the product and hence to the organization itself. Technical writers should help understand the text and not present any challenges to understanding. Click To Tweet In other words, if the readers don’t get the message, indeed, it means that the writer has failed to communicate the idea. Here we come to the conclusion that, in general, technical writers communicate ideas. Their top priority is to transform technical text into non-technical information.

It is worth mentioning that there are also technical writers who produce developer-focused documentation. Indeed, it is another broad dimension in the rapidly developing field of technical communication. Their task is to document all functions, parameters and new features or changes of the software. In this case, their role is just to facilitate the workflow of the developers and help them sort out all the details of the software.

There is nothing in the programming field more despicable than an undocumented program.

Edward Yourdon

What kind of documentation do you deal with?

The list can actually be endless, since every industry relies on the technical writers. Here we provide the most typical types of technical documentation.

Beginners, for instance, tend to write the following documents:

  • product description documents;
  • installation and  maintenance documents;
  • user manuals, step-by-step guides, tutorials.

Once you have become an advanced technical writer, you are responsible for:

  • system control documents;
  • requirements specifications;
  • test cases;
  • design documents.

5 stages of creating an awesome technical document

TC is about communicating technical things to people who may or may not be technically inclined. Click To TweetA good technical document should address the specific needs of the reader, nothing more and nothing less. We come up with  5 main stages of the successful document:

  • researching the product & audience;
  • planning the project;
  • writing the table of contents;
  • writing the topics;
  • review and amend.

What are the features of the great technical document?

  • accuracy;
  • consistency;
  • clarity;
  • conciseness.

Have you ever come across the poem “I Keep Six Honest Serving Men…” by Rudyard Kipling? If not, get down to reading it! Some lines from the poem have already become the call-to-action phrases and are frequently quoted by many technical writers:

|

I keep six honest serving-men
(They taught me all I knew);
Their names are What and Why and When
And How and Where and Who.
I send them over land and sea,
I send them east and west;
But after they have worked for me,
I give them all a rest.

The basic idea is that one should constantly ask himself these six simple questions before even starting to write anything: Who, What, Why, Where, When, and How. This concept is a key to writing a great technical document. However, what is more important, is to find the answers to all the questions and sometimes give those ‘six honest serving men’ a bit of rest. Otherwise, one day there might appear “One million Hows, two million Wheres, and seven million Whys!”. Don’t ever risk reaching such a dead-end!

Top Challenges in Technical Communication

Some people consider this job to be rather challenging. Others believe it to be quite rewarding. The opinions concerning this issue diverge significantly. In this section, we are going to dwell upon top challenges that technical writers tend to encounter on a daily basis. So, it is up to you to decide which side you agree with.

Creativity challenge

You may not agree with the statement that technical documentation does involve creativity, but we will try to provide the strong arguments for you to side with us. Technical communication is a synergy of the words, graphics and the writer’s style. Click To TweetThe document should not only be informative but also coherent. This issue, indeed, presents a great challenge. It is already the matter of art to explain technical things in plain language. Don’t you think it to be the creativity from the writer’s standpoint? The only difference between the literature and the technical documentation is that a literary work is designed for pleasure, whereas a technical document is intended to satisfy the informative purposes. In both cases, the writer’s style matters a lot. You don’t need the documentation until it is necessary. However, at one time or another we all need it.

Present to inform, not to impress. If you inform, you will impress. Fred Brooks

software engineer, computer scientist

Difficult SME

Have you ever asked yourself how it is possible to write technical documentation for the products which you may or may not be familiar with? Technical writers usually approach the subject matter experts (SMEs) in order to gather the raw material for the documentation. What would you do if the SMEs are not approachable?

One solution is to test the product on your own but it takes a lot of time. It’s true that people sometimes can be intolerable. We are all human beings, things happen. Technical writers should be persistent and so to say ‘torture’ experts with the questions. One great psychological hack is just to break the ice. Try to find some common interests, a nice topic to speak about. Be it a recent baseball game or a favourite book, somehow, you will definitely find the opportunity to ask for help or assistance. Believe, you will never get a refusal in such case.

Documentation management

Managing documents has always posed a huge challenge in business. As part of their job, technical writers deal with tens of thousands of various documents. Thus, they often need to refer to some powerful document management systems in order to optimize their workflow and save time.

Here we point out the key benefits of DMS:

  • reduced storage space;
  • better security;
  • convenient retrieval;
  • better backup;
  • facilitated collaboration.

Time management

It is worth admitting that a typical working day of the average technical writer is jam-packed. Some of you may argue that such job is the exceptional boredom, because it presupposes just the passive act of typing the technical content. We would state that this is not the case. Technical writing is also about communicating with people, meeting deadlines and managing several projects at a time. In order to manage your time and use it more efficiently, try out some great software tools. The next chapter discusses them in more details.

Efficiency is doing things right; effectiveness is doing the right things.

Peter Drucker

management consultant, educator and author

Great tools to overcome top technical writer challenges

It’s not a secret that technical writers do rely on some powerful software tools in order to optimize their workflow. There is no magic wand that will instantly turn you into a successful technical writer. Click To TweetSuffice it to say, it’s all about your knowledge, experience and determination.

By three methods we may learn technical writing: the first by education, which is the noblest; the second by methodology, which is the easiest; and third by planting your butt in a chair and pecking out the damn document, which is the bitterest. Andrew Plato

AnitianSecurity CEO

Career in technical communication is very promising. What a short video to understand what is the future of TechComm:

Technical writers don’t need to be computer nerds and know how to do computer programming. Nevertheless, they have to be tech-savvy, meaning that software tools should not present any problems for them. Here is the list of the best software for technical writers:

  • Confluence

Atlassian Confluence is considered to be the most powerful document management system that allows to manage the lifecycle of your technical documentation. This includes creating, drafting, reviewing, publishing and storing of the documents. In other words, it is a team collaboration software that is aimed to store company’s knowledge.

  • Trello & Jira

To be more productive and manage time more efficiently, we suggest using some powerful project management tools such as Jira or Trello. Trello is a free web-based project management application. It is mostly designed for small businesses in order to help people manage their workflow and organize their projects into boards. Jira provides not only project management functions but also bug and issue tracking. It is a commercial product, developed by Atlassian.

  • Ezvid & Stepshot

Good writing doesn’t happen overnight. It requires planning, drafting, rereading, revising and editing. Besides, technical writers are to provide the readers with the valuable visual info in order to facilitate their understanding. Very often short videos, graphics and images work much better than just a set of technical terms. High-quality visual content can add the real value to your piece of writing.

Ezvid is a free video editing and screen recorder software that is quite easy to use. With one click, you can record your screen and capture whatever appears on your computer. You can edit these videos, make speed changes, re-arrange, add text and image slides, spending on it minutes instead of hours.

StepShot may come in handy as a great step-by-step documentation tool in creating technical documentation, IT instructions, user support manuals, runbooks and reference guides. It captures screenshots for every click and provides automate descriptions for each of them. You can also edit the screenshots and add own comments to them.

  • Adobe FrameMaker

In a nutshell, Adobe FrameMaker is a great tool which provides the capability to author, edit, and publish complex multilingual technical content across mobile, web, desktop, and print platforms. It allows to work faster and smarter with advanced XML/DITA capabilities and publish content as responsive HTML5, Mobile App, PDF and EPUB. FrameMaker remains one of the best software for technical writers on the market today.

  • Adobe Illustrator & Adobe InDesign

Adobe InDesign helps technical writers develop things like posters, flyers, magazines, brochures, newspaper and book layouts. Functioning as a desktop publisher, InDesign works great for developing graphics and text together. Adobe Illustrator is a tool for creating and editing vector based illustrations such as logos and brand marks as well as other design elements. Whatever you create in Illustrator is scalable to the infinite power.

  • RoboHelp & MadCap Flare

RoboHelp & MadCap Flare are among the most popular help authoring tools. They are used by technical writers to create the help systems that are packaged with software products, delivered through web browsers or provided as files users can view on their computers.

Summing up, a technical writer is a person whose job is to get the right information to the right reader at the right time and at the right cost. Frankly speaking, there isn’t any secret to success. It is only the combination of your ambitions, hard work and learning from failure.

Content Marketing Manager
SHARES