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

The Ten Commandments of Technical Writing

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

thatdocslady

September 08, 2014
Tweet

More Decks by thatdocslady

Other Decks in Technology

Transcript

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

  3. 4 What do I want? • World domination through documentation

    • Not just for writers anymore! • Bringing “communication” back into “technical communication” • Sharing is caring
  4. 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
  5. 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
  6. 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!
  7. 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!
  8. 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!
  9. 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!
  10. 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!
  11. 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
  12. 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!
  13. 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!
  14. 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
  15. 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
  16. 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.
  17. 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)
  18. 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)
  19. QUESTIONS? COMMENTS? FLOWERS? TOMATOES? You can also ask me later

    here, here, here, and there: Email [email protected] Google+ [email protected] Twitter @thatdocslady Freenode thatdocslady