Technical writing overview

From Wikiversity
Jump to: navigation, search
File:TechWriting5.jpg
Technical Writers work with some of the smartest people in the world.

Who is a Technical Writer?[edit]


Technical writers write technical and software manuals, handbooks, technical guides and provide online help. Anyone who writes about technology for other people is typically referred to as a technical writer.

Most professionals require some technical writing skills. In the information technology realm, project managers and analysts write a large number of technical documents that must be clear and concise. A technical writer explains the product to the end user.

Pay is [1]good and working conditions are agreeable. It is mentally stimulating creative work, which requires someone who is both sociable and well read. Technical writers do not need to know how to program computers or have more than a general understanding of the technology, but they must have the ability to learn about a new product and then explain it to others. Those with training in journalism, teaching, and writing can grow to become excellent technical writers by studying the techniques of modern technical communication. Often, though, engineers and technicians most familiar with the technology, product, and process and have or develop writing skills become technical writers.

Technical writers enjoy learning and reading. They find writing comfortable, though they aren’t perfect, and typically revise their work many times. They are both creative and orderly. Most importantly, they put themselves in the end user’s position.

As an introductory course, only the most universal and important concepts are covered here. Later courses deal in depth with areas such as business analysis, documentation management, and other advanced topics.

What do technical writers do?[edit]

When technical writers approach a new piece of technology, they are inwardly observing their own lack of knowledge. As they interact with and learn the software, they identify the information needs of the software users. They must be able to communicate well with programmers and customers, and extract information from them in a professional and personable manner.

A technical writer's primary tool is the language. Secondarily, they use proprietary software like Microsoft Word, FrameMaker, and RoboHelp; or—increasingly—free and open-source documentation software such as Wiki. In the course of their careers, technical writers learn dozens of other software packages and tools, and then teach them to others.

Worldwide, there is a strong demand for technical writers. Overwhelmingly, they use the English language. Software companies require technical and user documentation of their products, and will continue to do so for the foreseeable future.

It's difficult for aspiring technical writers to get “a foot in the door.” Most employers are looking for technical knowledge and demonstrated experience. Completing this course, and creating a project portfolio of completed work, will open doors to a career in technical communications.

back to Technical Writing Level 1

Technical Writing at Wikiversity
TechWriting4.jpg

The Essential Skills of a Technical Writer[edit]

A good technical writer requires five important skills or characteristics:

1. Facility with technology

You must have the potential to grasp technology. You may have a bent towards one of the sciences, and can understand the inner workings of cells or atoms. Or you may be web savvy and know how to interpret code. Or maybe you’re just curious about how things work. You can learn technologies you don’t understand, if you have the motivation. I personally enjoy learning about complicated systems. This understanding brings a sense of achievement and knowledge that is rewarding at the end of the day.

2. Ability to write clearly

The essential skill of any technical communicator is to disambiguate. The core job is to study complicated things and explain them clearly. You can’t just pass off an explanation without understanding it completely. Writing about something, as opposed to talking about it, requires you to understand it thoroughly. Avoid passive voice and long sentence constructions. Define acronyms and avoid assumptions about what the user knows.

3. Talent in showing ideas graphically

Show ideas graphically as much as possible. People understand better when you can communicate visually. Images help make your writing clear.

4. Patience in problem-solving/troubleshooting

Unless you have patience, you’ll never make it. Much of IT work consists of problem solving. It’s amazing how a seemingly impossible problem can be solved with a little patience and persistence.

5. Ability to interact with SMEs (Subject Matter Experts)

Interacting with SMEs is one of the most overlooked skills in technical writing. You must be able to identify and interview people who posses knowledge important to your document. You can’t be shy about going after certain people to extract information—and you can’t be too proud to ask “dumb technical questions.” Much of this interaction can come about if you’re lucky enough to simply sit near SMEs.

Thanks to Tom Johnson for permission to use this material. [Edited once for clarity in context.] For more see his website I'd Rather Be Writing - Five Skills Every Technical Writer Needs

Technical Writing Basics[edit]

You can use any word processing program to create printed user guides. Free and open source software like OpenOffice and LibreOffice are good, but many employers expect you to have experience with proprietary tools such as MS Word and FrameMaker.

To create online content, you may use a proprietary program like RoboHelp for help files, or a web authoring tool for making web pages. We recommend that you also explore how platforms such as Wiki can be used for delivering user oriented instructions.

Wikipedia defines Technical Communication as:

The process of developing information products in technical communication begins with ensuring that the nature of the audience and their need for information is clearly identified. From there the technical communicator researches and structures the content into a framework that can guide the detailed development. As the information product is created, the paramount goal is ensuring that the content can be clearly understood by the intended audience and provides the information that the audience needs in the most appropriate format.

This means there are always at least three steps in every documentation project:

  1. Identify the audience
  2. Research and structure the content
  3. Ensure it is accurate and understood

| TWFred lecturing on the basics of writing a technical topic.

Technical Communication is a conversation[edit]

Lindsey Robbins of Blackbaud describes technical communication as a conversation between the user and the technical writer - in the sense that the technical writer must anticipate the questions a user would ask about the software. Robbins says:

"Sometimes, your users or constituents won't know the correct question to ask. In those situations, try to think out the questions for them and answer them in advance. Provide them with the conversation starter and they're more likely to be engaged.
"And remember: People don't have an infinite amount of time. They really will only participate in the conversation long enough to get their answer. Therefore, all your communication, whether it's real time or not, needs to be concise, clear, and efficient. Don't provide lots of and lots of text that users will balk at when they see."

Re-printed with the permission of Lindsey Robbins, from her article "Be Part of the Conversation"

Technical communication is sort of a translated conversation between the user and the developer of a product. The technical writer acts as the translator between the user and the developer. The technical writer understands what the developer wants to explain to the user about making use of the product. And so the technical writer bridges the communication gap between the user and the product developer.

Technical Writing Myths[edit]

In a recent article on his blog, Tom Johnson refuted several common myths about technical writing and the skills a technical writer must have. He believes the most common myths are:

  1. Technical writers spend most of their time writing.
  2. You can’t get a job in technical writing unless you have technical writing samples, but you won’t have samples until you have a job in technical writing.
  3. A technical writer who has years of experience is more knowledgeable than one with fewer years of experience.
  4. The tools you know are more important than your industry knowledge.
  5. Be careful about having a blog, because all employers google you and will find it.
  6. Technical writing academics are disconnected from the profession, and have only a tenuous idea about the actual practice of technical writing.
  7. You can’t have voice or style in technical writing. It must be objective. And the fewer contractions, the better.
  8. Technical writers aren’t allowed to contact users directly. They should get their information through the product manager, customer support, and marketing.
  9. You can single source material into all the formats your audience needs if you just learn the right tool or technology.
  10. You must be quite tech-savvy to be a good technical writer.

For Tom's full treatment of these myths, see his article "14 Widespread Myths about Technical Writing".

This material has been re-published here in an edited form. Thanks to Tom Johnson for allowing us to use his articles here.

A great future[edit]

Technical Writers communicate ideas. They design information, participate in the product development process, and manage complex documentation projects. Beginning software technical writers are often responsible for communications between the developers and the end-users of the software.

Business writing skills are useful for technical writers. All technical writers must write clearly, and communicate well with specialists. In fact, the field of Technical Writing is so vast it can be hard to define exactly what it is. This is why these sets of lessons concentrate mostly on technical writing for the software industry.

Beginning Technical Writers produce the following types of documents:

  • Product brochures, web sites, and other marketing tools that explain the benefits of the software to buyers.
  • User Guides, manuals, tutorials, and step-by-step task lists that guide new users learning the software.
  • Installation and maintenance guides that show the administrator and experienced user how to configure and troubleshoot the software.

As you advance in your career you may find yourself writing more advanced documents:

  • Design documents that describe the workings and interactions of the system.
  • Control documents that communicate project standards, configuration, schedule and work tasks.
  • Test cases that detail the required functionality so the software conforms to the specifications.

Documentation management includes:

  • Cost and schedule estimating.
  • Complex documentation project administration.
  • Setting standards and procedures.
  • Information management.

As you can see, there is a lot of room to learn and grow in the profession of technical writing.

How to edit Wiki

Wikiversity Main Page

back to Technical Writing Level 1