Slide 1
Slide 1 text
Tanja Roth
SUSE Documentation Team
Technical Documentation Specialist
[email protected]
Technical Writing
for Non-Writers
openSUSE Conference
Nuremberg, May 26th 2017
Slide 2
Slide 2 text
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
Slide 3
Slide 3 text
Contents
●
basic principles
●
best practices
●
quality assurance
●
exercise:
analyzing and optimizing a text
Slide 4
Slide 4 text
Basic Principles
Slide 5
Slide 5 text
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
Slide 6
Slide 6 text
Basic Principle #2
make it easy for the reader
●
to mentally process the information
●
to follow the instructions
●
to remember the information
Slide 7
Slide 7 text
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
Slide 8
Slide 8 text
Step into the reader's shoes!
Image: https://unsplash.com
Slide 9
Slide 9 text
Basic Principles
Conclusion
KISS (Keep It Simple and Short)
●
short sentences
●
simple grammar
●
simple words
Slide 10
Slide 10 text
Best Practices
How to make it easy for the reader
Slide 11
Slide 11 text
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)
Slide 12
Slide 12 text
Example
Task-based Information
https://www.suse.com/doc/sle-ha-12/install-quick/data/install-quick.html#sec_ha_inst_quick_test
Slide 13
Slide 13 text
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?
Slide 14
Slide 14 text
Writing
Consistency
●
be consistent
choice of words, spelling, punctuation
●
be parallel
phrases and structure
●
be short
Slide 15
Slide 15 text
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.
Slide 16
Slide 16 text
“Your language becomes clear and strong […] when you
can no longer take away.”
Isaac Babel
Slide 17
Slide 17 text
Structure
Approaches: top-down vs. bottom-up
create outline
then fill in details
first write down details
then organize them
Slide 18
Slide 18 text
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
Slide 19
Slide 19 text
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.
Slide 20
Slide 20 text
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?
Slide 21
Slide 21 text
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
Slide 22
Slide 22 text
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'
Slide 23
Slide 23 text
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'.
Slide 24
Slide 24 text
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.
Slide 25
Slide 25 text
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'.
Slide 26
Slide 26 text
“Easy reading is damn hard writing.”
Nathaniel Hawthorne
Slide 27
Slide 27 text
Words and Phrases
Keep It Simple
●
utilize
✔ use
●
indicate
✔ show, tell, say
●
prerequisite
✔ requirement
●
able to
✔
can
●
in order to
✔ to
Slide 28
Slide 28 text
Words and Phrases
Filler Words
●
avoid “filler words”
– simple, simply
– just
– basically
– easy, easily
●
avoid unnecessary modification
– already existing
– completely new
Slide 29
Slide 29 text
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!
Slide 30
Slide 30 text
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.
Slide 31
Slide 31 text
Summary
●
3 basic principles
●
information types
●
writing
●
structure
●
titles
●
sentences
●
words and phrases
●
instructions
●
warnings
Slide 32
Slide 32 text
Quality Assurance
Slide 33
Slide 33 text
Done? Not yet...
●
quality assurance:
– technical review
– structural review
– language review
●
remove unnecessary information (target group!)
●
get peer review
Slide 34
Slide 34 text
“To write is human, to edit is divine.”
Stephen King
Slide 35
Slide 35 text
Exercise
Analyzing and Optimizing a Text
Slide 36
Slide 36 text
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
Slide 37
Slide 37 text
Optimization
●
many ways to optimize
●
for a proposal, see etherpad.opensuse.org
Slide 38
Slide 38 text
Major Learnings?
Slide 39
Slide 39 text
“If I had more time,
I would have written a shorter letter.”
attributed to H.D. Thoreau, Voltaire, Augustin, Mark Twain, Blaise Pascal
Slide 40
Slide 40 text
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)
Slide 41
Slide 41 text
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
Slide 42
Slide 42 text
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
[email protected]
Design & Inspiration
openSUSE Design Team
http://opensuse.github.io/branding-guidelines/