Upgrade to Pro — share decks privately, control downloads, hide ads and more …

The Ten Commandments of Technical Writing

Cc4eb61ea6ff5b734785c6fc6c4be305?s=47 thatdocslady
September 08, 2014

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**

Cc4eb61ea6ff5b734785c6fc6c4be305?s=128

thatdocslady

September 08, 2014
Tweet

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
  3. 3

  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