Technical writing/Overview EE

• back to Technical Writing Level 1

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. 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 the following

• 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 it simple.
• Use active voice.
• Avoid logical fallacies.
• Use clear and concise language.
• Keep paragraphs coherent.

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, iWork Suite)
• Web tools
• Graphics packages
• Content management systems (CMS)
  • ClickHelp
  • Wiki
  • Confluence
  • Madcap Flare
  • Author IT
• Docbook
• Robo Help
• Adobe FrameMaker
• 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.

5. Interviewing Skills

Technical writers need to know how to ask questions and who is the best person to approach (e.g. Subject Matter Experts)

Basic technical 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

The Wikipedia definition of technical communication:

1. Personas (EE) How to identify and analyse your readers

Explore how Wiki can be used for delivering user-oriented instructions.

Test

1. What does a technical writer do? Researches, interviews, plans and creates a variety of technical documents that are meant to be used by a particular audience.
2. What sort of documents do technical writers write? Work instructions, User manuals, feasibility studies, specifications.
3. What skills does a technical writer need? Computer literate with a great attention to detail and excellent active listening skills. Must be able to write well and convey complex ideas in a manner easily understood for the reader.
4. What sort of people become technical writers? People who enjoy learning and sharing what they have learned with others. They know how to ask questions to gather the information they require for their project. They work and communicate well with others.
5. Why are you taking this course? (unmarked supplementary question) To hone my technical writing skills and to learn new things I don’t just want to be good at what I do, I want to be better than I am now. I want to grow my skills.

References

Forward to next module Personas (EE) How to use the correct language for the people who will read the documents

How to edit Wiki

Wikiversity Main Page

back to Technical Writing Level 1

The next unit Personas (EE) How to use the correct language for the people who will read the documents