THE TEN COMMANDMENTS OF
TECHNICAL WRITING
Mikey Ariel
Senior Technical Writer, Red Hat
Akademy, September 2014
Slide 2
Slide 2 text
2
Who am I?
●
Technical writer (6+ years in enterprise software)
●
Write the Docs EU community lead
●
Former scrum master (SAFe / Scrumban)
●
Technophile
●
Language nerd
●
Perpetually excited about all the things
Slide 3
Slide 3 text
3
Slide 4
Slide 4 text
4
What do I want?
●
World domination through documentation
●
Not just for writers anymore!
●
Bringing “communication” back into “technical
communication”
●
Sharing is caring
Slide 5
Slide 5 text
5
What do you want?
●
You are proud of your project
●
You want to share your project with the world
●
You want to increase contributions
●
Your project needs to scale
●
Your project needs to be n00b-friendly
Slide 6
Slide 6 text
6
The Ten Commandments of Technical Writing
●
Wait, what?
●
The first (best?) piece of technical writing
●
A good task can be described in 10 steps or fewer
●
Tone and style
●
Process management
●
Structure and format
●
Grammar conventions
Slide 7
Slide 7 text
7
Tone and Style
Slide 8
Slide 8 text
8
I am the one and only Voice.
●
Much contributor. So voice. Many tone.
●
The right voice for the right audience
●
Neutralize then localize
●
Veteran level: Tone guide!
Slide 9
Slide 9 text
9
Thou shalt not take the audience in
vain.
●
Who are my readers? What do they need?
●
Actual versus potential audience
●
Different content for different user levels
●
Simplified English
●
Veteran level: Audience-targeted content!
Slide 10
Slide 10 text
10
Process Management
Slide 11
Slide 11 text
11
Thou shalt have no other workflow
before the official workflow.
●
Cat herding without a plan
●
No such thing as too soon
●
Keep it simple, simple
●
Veteran level: Automate all the things!
Slide 12
Slide 12 text
12
Remember documentation in your release
schedule, to keep it holy.
●
Include doc discussions when you plan a release
●
Keep the writers in the loop during development
●
Make documentation a development requirement
●
Veteran level: README-driven development!
Slide 13
Slide 13 text
13
Honor thy contributors and thy
community.
●
A template is worth 1,000 style guides
●
Find the best tool for the job
●
Listen to your community
●
Remember your translators
●
Veteran level: Doc sprints!
Slide 14
Slide 14 text
14
Structure and Format
Slide 15
Slide 15 text
15
Thou shalt not overkill.
●
I like big books and I cannot lie
●
Attention span is getting shorte.... Ooh, squirrel!!
●
Bottom line first – TL;DR
●
Repetition, repetition, repetition... NOT
●
Content chunking helps skimming
Slide 16
Slide 16 text
16
Thou shalt steal, reuse, and adapt.
●
Plagiarize, plagiarize, plagiarize!
●
Content reuse and snippets
●
Fork, clone, push, credit
●
Veteran level: Convert all the things!
Slide 17
Slide 17 text
17
Thou shalt make unto thee diagrams,
screenshots, and code examples.
●
An image is worth 1,000 words
●
Code examples... or templates?
●
Multimedia content increases user coverage
●
Veteran level: Embed all the things!
Slide 18
Slide 18 text
18
Grammar Conventions
Slide 19
Slide 19 text
19
Thou shalt not commit ambiguity.
●
Pronouns
●
It is a cousin
●
They like to talk
●
This that and the other
●
Participles or gerunds?
●
Use the script for invoking methods
●
Transitive verbs
●
You have to install this tool
●
The user has privileges
Slide 20
Slide 20 text
20
Thou shalt not commit ambiguity.
●
Passive voice
●
Dependencies are found by scanning binaries
●
This script is run to modify configuration
●
Could've should've would've
●
This operation should start your application
●
You could start the application with this operation
●
Context
●
Step 1: Run the command
Slide 21
Slide 21 text
21
Thou shalt covet simple grammar.
●
Adverbs
●
Create a new file
●
Run this script to easily set properties
●
Jargon
●
LBJ took the IRT down to 4th St USA
●
Etc., etc., etc...
●
Compound sentences
●
You can revert your changes, and if you perform the
rollback correctly, you can restore your system to its
previous state, before you made the changes.
Slide 22
Slide 22 text
22
Thou shalt covet simple grammar.
●
Keep it simple, present
●
This command will modify properties
●
Perfectly redundant
●
If you have installed the application
●
Contractions and possessives
●
Don't, it's, can't
●
Things cannot own other things
●
Parentheses
●
Edit the file (located in your home directory)
Slide 23
Slide 23 text
23
Extra credit (read: awesome things and people)
Style and tone
●
Engage or die: Four Techniques for Writing Indispensable Docs
(Kelly O'Brien)
●
Tone in Documentation
(Jessica Rose)
Workflow and process
●
README-Driven Development
(Thomas Parisot)
●
Writing Docs: A Beginners Guide to Writing Documentation
(Eric Holscher)
Community
●
Write the Docs (Docs or it didn't happen!)
●
No Onions in My Salad: How to Manage Emerging Communities
(Dr. Paul Adams)
Slide 24
Slide 24 text
QUESTIONS? COMMENTS?
FLOWERS? TOMATOES?
You can also ask me later here, here, here, and there:
Email mariel@redhat.com
Google+ mikeymay972@gmail.com
Twitter @thatdocslady
Freenode thatdocslady