The Ten Commandments of Technical Writing

Does your open source project need better documentation? Do you wish that new users could on-board to your software more easily? Do you feel that your contributors are discouraged from documenting their code?

Assuming that the answer to at least one of these question is a bright flashing neon YES, this talk goes through the basic principles of technical communication in the context of open source projects. Themes include tone, style, grammar, workflow, and tools.

This talk is based on my personal experience as a technical writer and scrum master in the software industry for the past 6 years, as well as on my adventures in the open source communities for the past year.

**This version of the talk was presented at the KDE Akademy in Brno, September 2014**

Transcript

1. THE TEN COMMANDMENTS OF TECHNICAL WRITING Mikey Ariel Senior Technical Writer, Red Hat Akademy, September 2014
2. 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
4. 4 What do I want? • World domination through documentation • Not just for writers anymore! • Bringing “communication” back into “technical communication” • Sharing is caring
5. 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
6. 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
7. 7 Tone and Style
8. 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!
9. 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!
10. 10 Process Management
11. 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!
12. 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!
13. 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!
14. 14 Structure and Format
15. 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
16. 16 Thou shalt steal, re­use, and adapt. • Plagiarize, plagiarize, plagiarize! • Content reuse and snippets • Fork, clone, push, credit • Veteran level: Convert all the things!
17. 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!
18. 18 Grammar Conventions
19. 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
20. 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
21. 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.
22. 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)
23. 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)
24. 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