Technical Writing Training for Engineers

Technical Writing for Engineers

© parson AG

Standardizing and Structuring Information

Basic Principles and Introduction

Levels of Structuring Information

Exercise

User-Oriented Writing

Target Group Analysis

Topic-Based Writing

© parson AG Technical Writing for Engineers 2

Day 1

Benefits of Standard and Structure

Manufacturer:

• Easy and efficient document creation

• More consistency

• Shorter texts

• Less redundancy

• More completeness

• Better reuse of text modules

Users:

• Improved orientation

• Improved comprehensibility

• More acceptance


One Sentence – Many Possibilities

Speaking (writing) is acting!

Every sentence has a function (intention) – but which?

The door is open. „I just realized.“

„Please shut the door.“

„It‘s your fault. You left it open.“

„Please come in.“

Clear function Successful communication Structured Documentation


Exercise

Assign functions to the following sentences:

To upgrade the Admin module, you need to first remove it and then reinstall it.

To remove the module, open the “Module Management” page and select the Admin module from the list of installed modules. Then click the “Remove” button.

The Admin module is removed.

Make sure that no users are logged in. All user sessions are automatically closed when removing the module.

After removing the module, you automatically return to the “Module Management” page.

On that page, click “Install New Module” and choose the folder where the Admin module file is stored.

The module is installed.

Description

Instructions

Step result

Warning

Step result

Instruction

Step result


• Information product = functional structures with clearly defined elements

• Functional structures on different levels

• Clear definitions of all elements

• Qualitative and formal rules for authors

• Standardized creation and production

• User-oriented approach

Common methods for classifying information: Information Mapping©,

Information Design™

Principles of Structured Documentation


Levels of Information Structures

Information product

Complex macro structures (e.g. task)

Secondary macro structures

(e.g. step in task)

Micro structures (e.g. markup)


Target Audience Analysis

• Identify target audiences

• Analyze information requirements of target group

• Analyze product

Methods

• Personas

• Responsibility matrix


Questions to Ask

• Who uses the product? Are there different types of users?

• What do the users do with the product?

• What does my audience already know about the product?

• What level of education does my target audience have? Are they familiar with

terms commonly used in the industry?

• What is the level of English proficiency of my target audience?

• What does my audience need to know?

• In which scenarios will the documentation be read? Are environmental

conditions relevant (such as lighting)?


Personas

What is a Persona?

• Fictitious person with individual characteristics and behavior

• Represents actual users

• Wants to solve specific problems

Personas support authors to write user-oriented documentation.

Important Rules

• A Persona must have the characteristics of a potentially alive person, not

statistical values (such as 1.2 children).

• Clear, detailed, compact description


User-Oriented Content

• When deciding what to document, consider the users goals.

• Choose task titles from the users point of view, not the systems.

• Write titles in user language so that users recognize their goals.

• Focus the user’s attention on the action, use action verbs (imperatives).

• Eliminate introductory sections that provide little or no valuable information to

users.


Topic-Based Writing

• Topic: discrete piece of content that is about a specific subject, has an

identifiable purpose, and can stand alone.

• Topics always have a title.

• Topics answer one central question.

– How to … ?

– What is … ?

– How can I … ?

– What is the meaning of … ?

• You can reuse topics in different contexts and easily replace them.

• Cross references link concepts, references, and tasks with each other.


Topic Types

Topics have a specific function. The basic functions are:

• Instruct

• Inform

• Provide facts

Task (Instruct)ProceduresInstructionalUser-oriented

Concept (Inform)DescriptiveHelp to understandBackground information

Reference (Provide facts)Used to look up factsWindow descriptionsParametersValues


Grammar and Punctuation

Clarity

Minimalistic Writing

Typical Mistakes

Day 2

Style Guide

Terminology

Figures

Legal Requirements and Safety Notes

Best Practices


Commas

Serial comma

• Place a comma between all elements of a series, including the conjunctions

• The serial comma removes ambiguity.

x I would like to thank my parents, Ayn Rand and God.

The first letters of the alphabet are a, b, and c.

After introductory phrases at the beginning of a sentence

• If clauses:

If the monitoring device reports an error, call the support.

• (Optional) Adverbial phrases:

In the Project Management window, click Create Project.

After installing the device, set up the configuration files.


That and Which

that introduces a restrictive relative clause.

• Restrictive clauses are essential to the meaning of the main clause.

• Do not place a comma before that.

Remove the screw from the Measurement Module that is connected to the Elevation

Table.

There are several Measurement Modules, one is connected to the Elevation Table.

which introduces non-restrictive clauses.

• You can omit a non-restrictive relative clause without changing the meaning of the main

clause.

• Always place a comma before which.

Remove the screw from the Measurement Module, which is connected to the Elevation

Table.

There is only one Measurement Module. It is connected to the Elevation Table.


Active vs. Passive Voice

Voice indicates the relation of the subject to the action of the verb. When the verb

is in the active voice, the subject acts.

• Use active voice as much as possible. Active voice is more precise and direct.

Also, it focuses on the user.

• Only use passive voice when the acting person is unknown or irrelevant.

x The software must be backed up by the administrator every week.

The administrator must back up the software every week.

Back up the software every week.

x The settings must be made after installation of the software.

Configure the software after the installation.


Fewer Words

Delete meaningless words and avoid commonly used words that provide no value

to the sentence or paragraph.

• Words that can be removed in most cases:

x kind of, actually, really, generally, practically, essentially, basically

x completely, really, quite, totally, very, rather

x essentially, particular, certain, various

• Replace long verbs with shorter, simpler forms:

x utilize use



Warning Signals

Signal Word Description Color and Symbol

Danger Hazardous situation that, if not avoided, will result in death or serious injury.

Warning Hazardous situation that, if not avoided, could result in minor personal injury or serious injury or death.

Caution Hazardous situation that, if not avoided, could result in minor or moderate injury.

Notice Information considered important but not hazard related.



parson AG Chrysanderstr. 69A 21029 HamburgGermany

Photo credits

Fotolia.com

• Anatoly Maslennikov

• Ievgen Melamud

• Coramax

http://themetapicture.com/

Tel. +49 (0)40 7200 500-0

e-mail: [email protected]

Education

Technical Writing Training for Engineers