Successfully reported this slideshow.
We use your LinkedIn profile and activity data to personalize ads and to show you more relevant ads. You can change your ad preferences anytime.

Technical Writing Training for Engineers

3,720 views

Published on

Technical writing training for engineers, software developers, or technicians. We teach you how to write for a specific target group and create well-structured documents.

Published in: Education
  • Be the first to comment

Technical Writing Training for Engineers

  1. 1. Technical Writing for Engineers © parson AG
  2. 2. 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
  3. 3. 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
  4. 4. 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
  5. 5. 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
  6. 6. • 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
  7. 7. 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
  8. 8. 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
  9. 9. 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
  10. 10. 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
  11. 11. 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
  12. 12. 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
  13. 13. Topic Types Topics have a specific function. The basic functions are: • Instruct • Inform • Provide facts Task (Instruct) Procedures Instructional User-oriented Concept (Inform) Descriptive Help to understand Background information Reference (Provide facts) Used to look up facts Window descriptions Parameters Values © parson AG Technical Writing for Engineers 13
  14. 14. 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
  15. 15. 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
  16. 16. 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
  17. 17. 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
  18. 18. 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
  19. 19. © parson AG Technical Writing for Engineers 19
  20. 20. 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
  21. 21. © parson AG Technical Writing for Engineers 21 parson AG Chrysanderstr. 69A 21029 Hamburg Germany Photo credits Fotolia.com • Anatoly Maslennikov • Ievgen Melamud • Coramax http://themetapicture.com/ Tel. +49 (0)40 7200 500-0 e-mail: contact@parson-europe.com www.parson-europe.com

×