technical writing training for engineers
TRANSCRIPT
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
© parson AG Technical Writing for Engineers 3
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
© parson AG Technical Writing for Engineers 4
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
© parson AG Technical Writing for Engineers 5
• 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
© parson AG Technical Writing for Engineers 6
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)
© parson AG Technical Writing for Engineers 7
Target Audience Analysis
• Identify target audiences
• Analyze information requirements of target group
• Analyze product
Methods
• Personas
• Responsibility matrix
© parson AG Technical Writing for Engineers 8
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)?
© parson AG Technical Writing for Engineers 9
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
© parson AG Technical Writing for Engineers 10
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.
© parson AG Technical Writing for Engineers 11
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.
© parson AG Technical Writing for Engineers 12
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
© parson AG Technical Writing for Engineers 13
Grammar and Punctuation
Clarity
Minimalistic Writing
Typical Mistakes
Day 2
Style Guide
Terminology
Figures
Legal Requirements and Safety Notes
Best Practices
© parson AG Technical Writing for Engineers 14
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.
© parson AG Technical Writing for Engineers 15
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.
© parson AG Technical Writing for Engineers 16
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.
© parson AG Technical Writing for Engineers 17
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
© parson AG Technical Writing for Engineers 18
© parson AG Technical Writing for Engineers 19
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 Technical Writing for Engineers 20
© parson AG Technical Writing for Engineers 21
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]