Technical Writing Overview

Introduction

This overview module and the following modules have been written intentionally in the style of a technical document. This is so that the reader sees the type of content needed for technical documents from the outset. The language of the document has been kept simple to allow easy translation. Wherever possible, the modules conform to the rules they state.

These modules have been taught to small, eight-student classes of students. Each module takes 1 hour to teach. Additional examples and exercises were used.

Technical writing is a discipline.

Technical writing is not difficult.

In this module and the modules that follow, there are a set of rules that must be applied.

Most of these rules apply to all technical writing, some rules only apply to certain types of documents.

Most of the rules are independent of the style used.

If you learn the rules and apply them, then you will write better documents.

It is easier to write using a rigid set of rules than to have no rules.

The rules also help people like:

• Business (System) Analysts
• Project and Product Managers
• Solution (System) Architects

Technical writing rules

The basic rules are:

• Write simple sentences.
• Use words that your reader will understand.
• Use lists.
• Use pictures (sparingly, if localizing the documentation).
• Use consistent terminology.
• Do not waste your reader's time by explaining things they already know (e.g., copy and paste procedures).
• Make short and simple.
• Use active voice.
• Avoid logical fallacies.

The difference between a technical writer and a technical communicator

• A technical writer writes documents (user guides, administrator guides, online help, etc.)
• A technical communicator is a newer term for the same job acknowledging that the writer needs to do more than simply write documents, but also needs to understand the intricacies of systems, processes, business flows, and can develop content that includes more technical reference and information.

Technical writers produce written and visual information for customers.

Technical writers write the following types of documents

To design and improve the product

• Requirement specifications, document the features required in the product
• Development requests, that document tasks for developers
• Change requests, that document new features that the customer wants
• Design specs, what a product should look like when it is manufactured

To sell the product

• Technical and product briefs
• Product brochures
• Web site content
• Press releases

To help the customer administer the product

• User guides
• Configuration guides
• Application guides
• Administration guides
• Data sheets
• Maintenance and trouble shooting guides that show the administrator and experienced user how to configure and troubleshoot the product

To help the staff or the customer operate the product

• Use case-based tutorials
• Step-by-step task lists
• Online help in CHM or HTML

To test and install the product

• Test Cases: To test the product and detail its required functionality
• User Acceptance Test (UAT): Run test cases for the customer in order to confirm that each function that is required for the product to run properly is, in fact, doing so
• Installation Guides: To ensure that the product will be safely installed by the customer
• Technical Writing Requirements and Functional Specifications (TWRFS): Document the needs, goals, and environment of the target product user, and then explain how these elements can be translated into functions within the product in order to satisfy said items.
• Design Documents: Describe the workings and interactions of the system.
• Control Documents: Communicates project standards, configuration, schedule and work tasks.

Management documentation

Management documentation includes:

• Cost and Schedule Estimates
• Complex Project Administration
• Standards and Procedures
• Information Management

What tools do technical writers use?

A technical writer's primary tool is language. A technical writer also uses

• Word processors (MS Word, Open Office)
• Web tools
• Graphics packages
• Content management systems (CMS)
  • Wiki
  • Confluence
  • Madcap Flare
  • Author IT
• Docbook
• Robo Help
• Screen shot capturing tools
  • MWSnap (Free-ware)

The essential skills of a technical writer

These skills are important:

1. The ability to use a computer

It is possible to write manuals with just paper and a pen but most people don't.

Most products include software that require screen-shots to explain fully, screen-shots require a computer.

2. The ability to write clearly

Technical writers

1. Study complicated things
2. Remove all doubt about a subject
3. Explain complex topics in simple terms
4. Add diagrams or screenshots
5. Define abbreviations
6. Avoid
   • Passive sentences (e.g. "Mistakes have been made.")
   • Long sentences

3. The ability to show ideas graphically

If you show an idea with a picture or diagram, then the reader understands the concepts better.

4. The ability to listen

Technical writers must listen carefully to the experts and then translate their concepts in layman's terms.

Basic technical writingal writing"

The process of writing:

• Plan the document
• Collect and organize your information. (Consult the experts on the subject if necessary)
• Find out who will be reading the document - your audience
• Draft the document
• Revise it
• Have a colleague review and edit it for style and language
• Have one of your experts review and edit it to validate the accuracy of the information that was included
• Publish the document

Test

1. What does a technical writer do?
2. What sort of documents do technical writers write?
3. What skills does a technical writer need?
4. What sort of people become technical writers?
5. Why are you taking this course? (unmarked supplementary question)