Technical Writing for Non-Writers

You need to write (technical) texts now and then? But you are not sure how to structure them, how to phrase your content, or how to best address your readers? This workshop shows you how to optimize texts to make them easier to understand (and translate). Get to know universal principles that can be applied to a wide variety of text types - including release notes, bug reports, error messages, or e-mails.

Transcript

1. Tanja Roth SUSE Documentation Team Technical Documentation Specialist taroth@suse.com Technical Writing for Non-Writers openSUSE Conference Nuremberg, May 26th 2017
2. About Me Tanja Roth • technical writer for + 15 years • in mechanical engineering, medical technology, information technology • joined SUSE in 2005 • plays drums and percussion • organizes community drum circles Photos: private
3. Contents • basic principles • best practices • quality assurance • exercise: analyzing and optimizing a text
4. Basic Principles
5. Basic Principle #1 change perspective! ➢ take audience’s point of view Image: https://unsplash.com change perspective! ➢ take audience’s point of view change perspective! ➢ take audience’s point of view change perspective! ➢ take audience’s point of view change perspective! ➢ take audience’s point of view
6. Basic Principle #2 make it easy for the reader • to mentally process the information • to follow the instructions • to remember the information
7. Basic Principle #3 consider readers ... • who are frustrated • who don't have much time • who work in a noisy environment • who don't speak the document's language as their first language
8. Step into the reader's shoes! Image: https://unsplash.com
9. Basic Principles Conclusion KISS (Keep It Simple and Short) • short sentences • simple grammar • simple words
10. Best Practices How to make it easy for the reader
11. Information Types • distinguish descriptive vs. task-based • descriptive: basic information, concepts, reference • task-based: how to achieve a certain goal? • most documentations are a mixture of both types • for orientation: clearly separate the types (e. g. title, layout)
12. Example Task-based Information https://www.suse.com/doc/sle-ha-12/install-quick/data/install-quick.html#sec_ha_inst_quick_test
13. Writing Target Group, Function • know your audience – level of details (newbie vs. experienced user) – involve the reader: 'you' • form follows function – what is the purpose of … a word, a sentence, a paragraph, a section? e. g. instruction? description? warning?
14. Writing Consistency • be consistent choice of words, spelling, punctuation • be parallel phrases and structure • be short
15. Writing 'Empty Calories'? An effective business requirements analysis should be performed to determine the right level of security and hardening to be applied to a server or defined as part of a baseline server build. To find the right level of security and hardening for a server, analyze your business requirements.
16. “Your language becomes clear and strong […] when you can no longer take away.” Isaac Babel
17. Structure Approaches: top-down vs. bottom-up create outline then fill in details first write down details then organize them
18. Structure General Principle • the following principle can be applied to most text types: – intro: invite reader in – brief background: state the problem – share the news: name the solution – get technical: how to solve? – conclusion: important facts, next steps
19. Example Structure (General Principle) As a car driver, you have probably found yourself in the following situation: Getting stuck on the side of the road with a flat tire. As no help is in sight, you need to change the tire yourself: 1. Apply the hand brake and put the car into a parking position. 2. Place a heavy object in front of the tires. 3. Take out the spare tire and the jack. […] After you have successfully installed the new tire, put the old tire in the trunk and take it to a mechanic.
20. Structure Readers' Perspective • complex information: split into chunks – Miller's Law: magical number 7 ± 2 • different types of readers: – reading from A-Z, browsing, searching table of contents • task analysis – focus on goals – does structure reflect the user's goals?
21. Structure Order, Hierarchy • first things first: what all users need to know, need to know early, is not optional 4.1 Managing User Accounts 4.2 Enforcing Password Policies 4.3 Managing Quotas • flat hierarchy – 3 levels: 1. – 1.1 – 1.1.1 – be pragmatic, not scientific – avoid 'lonely sections': 1. – 1.1 – 2. – 2.1 – 2.2
22. Titles How to Phrase • what is it about? • does title reflect the information type? – descriptive: use nouns (Types of Fencing) – task-based: use verbs (Installing 'Foo') • distinctive information first – How to install 'foo' → Installing 'Foo' – How to set up 'foo' → Setting up 'Foo' – How to test 'foo' → Testing 'Foo'
23. Sentences General • rule of thumb: one idea, one sentence • first things first ✗ The PIN, which must not be noted on the credit card, consists of 4 digits. ✔ The PIN consists of 4 digits. Do not note the PIN on the credit card. • instructions: where to act? what to do? ✗ Search for 'foo bar' in /etc/hosts. ✔ In /etc/hosts, search for 'foo bar'.
24. Sentences Avoid Interruptions • particles: move to beginning or to end however, nevertheless, therefore, for example, if necessary ... ✗ They are not, however, marked as installed in the package manager. ✔ However, they are not ... • same goes for (long) commands • phrasal verbs: keep together ✗ You can gracefully shut the server down. ✔ ... shut down the server.
25. Sentences Avoid Ambiguities • titles ✗ Clone Resource Agent Requirements ✔ Requirements for Clone Resource Agents • “-ING” forms of verbs: what are they referring to? ✗ Encrypt the password using 'grub2-mkpasswd-pbkdf2'. ✔ Encrypt the password by using 'grub2-mkpasswd-pbkdf2'.
26. “Easy reading is damn hard writing.” Nathaniel Hawthorne
27. Words and Phrases Keep It Simple • utilize ✔ use • indicate ✔ show, tell, say • prerequisite ✔ requirement • able to ✔ can • in order to ✔ to
28. Words and Phrases Filler Words • avoid “filler words” – simple, simply – just – basically – easy, easily • avoid unnecessary modification – already existing – completely new
29. Instructions • task: use steps, arrange in order of use • name goal and requirements (upfront) • one action per step • 7-10 steps, if more: split up into separate procedures • if user needs to take action, use active voice: the system is configured → configure the system • background or concepts: before the procedure, not within!
30. Warnings • add before step/action where danger arises • American standard ANSI Z535: – signal word – type and source of danger (e. g. in title) – possible consequences – how to avoid danger? Warning: Loss of Data Installing SUSE Manager on a physical machine will completely erase any data on the hard disk that is used for installation. Before you start the installation process, create a backup of your hard disks.
31. Summary • 3 basic principles • information types • writing • structure • titles • sentences • words and phrases • instructions • warnings
32. Quality Assurance
33. Done? Not yet... • quality assurance: – technical review – structural review – language review • remove unnecessary information (target group!) • get peer review
34. “To write is human, to edit is divine.” Stephen King
35. Exercise Analyzing and Optimizing a Text
36. Example Text • see etherpad.opensuse.org • tasks (~ 20 minutes): – identify functions of snippets (descriptions, requirements, individual steps, warnings, results, goals) – identify problems (structure? titles? sentences? words? lists? procedures? warnings?) – rewrite and try to optimize
37. Optimization • many ways to optimize • for a proposal, see etherpad.opensuse.org
38. Major Learnings?
39. “If I had more time, I would have written a shorter letter.” attributed to H.D. Thoreau, Voltaire, Augustin, Mark Twain, Blaise Pascal
40. Further Reading - 1 DeRespinis, Francis et al. The IBM Style Guide - Conventions for Writers and Editors ISBN 978-0-13-210130-1 (416 p., 2011) Hargis, Gretchen et al. Developing Quality Technical Documentation – A Handbook for Writes and Editors ISBN 978-0131477490 (445 p., 2004) Kohl, John R. The Global English Style Guide: Writing Clear, Translatable Documentation for a Global Market ISBN 978-1-59994-657-3 (310 p., 2008)
41. Further Reading - 2 Achtelig, Marc How to Write That F***ing Manual – Ohne Umschweife zu benutzerfreundlichen Handbüchern und Hilfen Bilingual edition: English + German ISBN 978-3-943860-01-6 (256 p., 2012) SUSE Documentation Style Guide
42. License This slide deck is licensed under the Creative Commons Attribution-ShareAlike 4.0 International license. It can be shared and adapted for any purpose (even commercially) as long as Attribution is given and any derivative work is distributed under the same license. Details can be found at https://creativecommons.org/licenses/by-sa/4.0/ General Disclaimer This document is not to be construed as a promise by any participating organisation to develop, deliver, or market a product. It is not a commitment to deliver any material, code, or functionality, and should not be relied upon in making purchasing decisions. openSUSE makes no representations or warranties with respect to the contents of this document, and specifically disclaims any express or implied warranties of merchantability or fitness for any particular purpose. The development, release, and timing of features or functionality described for openSUSE products remains at the sole discretion of openSUSE. Further, openSUSE reserves the right to revise this document and to make changes to its content, at any time, without obligation to notify any person or entity of such revisions or changes. All openSUSE marks referenced in this presentation are trademarks or registered trademarks of SUSE LLC, in the United States and other countries. All third-party trademarks are the property of their respective owners. Credits Template Richard Brown rbrown@opensuse.org Design & Inspiration openSUSE Design Team http://opensuse.github.io/branding-guidelines/