Write Guide Text

Technical writing is a little different from what you've done in other classes, so we created this "cheat sheet" of sorts to help prevent you from committing any word crimes. For further instruction on technical writing (and tips on how to write guides like “How To Use Your Samurai Sword For Zombie Defense”) check out the Tech Writing Handbook.

  • Gear your writing towards an audience with little technical knowledge. Remember, you might know all about this fix, but your audience doesn't (yet). Try to avoid using complex jargon or technical terms that could be confusing for a reader doing the fix for the first time.

  • Use the active voice. You're telling someone what to do in your guides, so tell them something to do. Simply stating that a component can be removed is passive and weak.

  • Be clear and descriptive, yet concise. Writing instructions that people actually want to read requires finding a middle ground between vagueness and verbosity. Read your own text out loud to yourself. You'll quickly have a feel for whether or not you've found the happy medium.

  • Write complete sentences. Don’t let those bullet points deceive you—proper grammar is critical to a clear and comprehensible guide. Remember to include all punctuation, including commas and periods.

  • Use articles like “a,” “and,” and “the.” As a reader, articles tell your brain that a noun is coming. When it comes to technical writing, it's commonplace to see articles dropped completely—but for those of us who aren't used to technical documents, this makes for rough reading. Gear your writing to a general audience, and use articles. We not robot, after all.

  • Identify parts and tools correctly. This might sound obvious, but make an extra effort to use the correct name for what you're describing, so that you can write clear directions.

  • Keep it simple. Avoid writing obvious steps like “Remember to keep track of your screws,” or “Locate component X.” Your readers will quickly tire of reading tedious or repetitive instructions, but they’ll thank you for text that is accurate, to-the-point, and concise.

  • Your first step should dive right in to the procedure. There's no need for a step showing the tools necessary for the Fast Fix. Instead, make sure to list the necessary tools under the Tools section of your guide.