Technical writing/Overview

• How to edit Wiki

• Wikiversity Main Page

• Back to Technical Writing Level 1

Who is a Technical Writer?

• "What is Technical Writing" - Warren Clendining, Mount Royal University Continuing Education instructor (YouTube Video)

• Technical Writing in 20 minutes - Part 1, Cherryleaf (YouTube Video)

• TWFred lecturing on the basics of writing a technical topic (YouTube Video)

Most professionals require some technical writing skills. In information technology, project managers and analysts write technical documents that must be clear and concise.

A technical writer explains the product to the end-user, by creating:

• Technical and Software Manuals
• Handbooks
• Technical Guides
• Online Help

Technical writing is mentally-stimulating, creative work, and 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 can have or develop writing skills to 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.

This introductory course covers only the most universal and important concepts in technical writing. Later courses deal in depth with areas such as business analysis, documentation management, and other advanced topics.

What do technical writers do?

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 language, tools such as Microsoft Word, FrameMaker, and RoboHelp; or—increasingly—free and open-source documentation software such as Wiki, are secondary considerations. 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 The Essential Skills of a Technical Writer A good technical writer requires six important skills or characteristics: 1. General ability to write The most important skill is to be able to write extended essays easily. You can test this skill on NaNoWriMo. Also be sure to use correct spelling and grammar (you cannot use GRAMMARLY, MS Word, etc etc…on the exam. And the quiz only accepts answers spelled correctly.) 2. 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. 3. 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. 4. 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. 5. 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. 6. 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 possess 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

You can use any word processing program to create printed user guides. Free and open-source software like LibreOffice, OnlyOffice, and OpenOffice (discontinued) are good, but many employers expect you to have experience with proprietary tools such as MS Word and Adobe 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 it 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

Lindsey Robbins of Blackbaud describes technical communication as a conversation between the user and the technical writer - the writer must anticipate the user's questions. 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 and lots of text that users will balk at when they see."

Reprinted with the permission of Lindsey Robbins, from her article "Be Part of the Conversation".

Technical communication is the act of translating between user and developer, with the technical writer as translator. The technical writer understands what the developer wants to explain to the user about using the product, thus the technical writer bridges the communication gap between user and developer.

Technical Writing Myths

In an 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

Technical Writers:

• communicate ideas
• design information
• participate in the product development process
• manage complex documentation projects.

Junior software technical writers are often responsible for communications between the developers and the end-users.

Business writing skills are useful for technical writers. All technical writers must write clearly, and communicate well with specialists. The field of Technical Writing is large and can be hard to define. For this reason these lessons concentrate mostly on technical writing for the software industry.

Junior 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:

• Requirement Specifications that document the needs, goals, and environment of the users of the software.

• 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