How to be a lousy technical writer

Some tongue-in-cheek observations:

  • Wait for the information to come to you because it’s “supposed to”.
  • Take edits personally because “developers can’t write”.
  • Skip project meetings because they’re “too technical”.
  • Ignore learning a technology because you’re “not a programmer”.
  • Stay quiet on user interface suggestions (or bugs you find) because “nobody listens to the tech writer”.
  • Avoid planning document deliverable dates because “they’re going to change anyway”.
  • Don’t [insert task here] because “it’s not my job”.

Full disclosure: I’ve thought each of these things at least once in my career. We all have. Just don’t let them dictate your actions.

11 steps to writing software documentation

This is what I do, but your situation might vary.

  1. Meet with the project manager (PM) to learn the following:
    • software business cases (What problems does it solve?)
    • doc needs (User guide? Release notes? Admin guide?)
    • doc audience (External customers? Internal business units?)
    • estimated deployment dates to Quality Assurance (QA) and production environments
    • name of the lead developer
  2. Ensure the PM adds you to any project meetings or Agile ceremonies.
  3. Ask the lead developer for access to the software’s development environment. Ensure they’re okay with you playing hard with it.
  4. Write chapter and section headings for tasks based on the business cases. Start them with verbs (“Add a user”) and organize them into a logical process flow.
  5. Play hard with the software. Note any bugs, misspellings, confusing user interface elements, etc., and pass them on to the lead developer.
  6. Write the steps needed to complete each task. Start each step with a verb (“Click Add User” or “Type the user’s name”).
  7. Complete a review draft 1-2 weeks before QA deployment and send it to the project manager and lead developer for review.
  8. Edit the draft as needed and obtain sign-off from the PM and lead developer.
  9. Send it to the QA team as a reference for their testing. Update the document with changes that come out of QA.
  10. Publish the document with production deployment.
  11. In a perfect world, all these steps flow smoothly and the project finishes on time. But we do not live in a perfect world and I’ve never had a project flow smoothly. Dates will be missed, review requests will be ignored, changes will be implemented without you knowing. So the most important step of all: Keep calm, adapt, and carry on.

Say “NO” to alphabet soup

Write out your acronyms the first time you use them on the page.

Just because you know GCP, AWS, and the web programming language on which JSON is based, doesn’t mean your readers do. If they do, they’ll skim over your description. If they don’t, you’ll save them a Google search.

That said, know your audience. Web developers should know HTML as well as baseball managers know the difference between WHIP and ERA.

In those cases, a link to a definition is nice.

Flatten the curve

From a technical communication perspective, “flatten the curve” is about as brilliant as it gets. The graphs convey a complex topic in a way that anyone with an 8th grade education can understand.

ILLUSTRATION: SAM WHITNEY; CDC

This level of clarity is something to which all technical writers should aspire.

What are software release notes?

Release notes tell customers what changed between, say, App 1.0 and App 2.0. At minimum, software release notes should have the following:

  • A list of new features and the value they add to the app.
  • Known issues (bugs) and workarounds.
  • If for App 2.0, give a status on the known issues listed in App 1.0’s release notes. Were they fixed or do they still exist? If they still exist, are there any new workarounds?

Release notes should not include future features or promises that a bug will be fixed in the next release. How can a customer use a future feature, and what if the bug doesn’t get fixed in the next release?

Think of release notes like the ingredients list on a box of Cheerios: you won’t find ingredients they plan to add next year.

Technical writing: The perfect job for introverts and quarantines

I spend 90% of my day writing, editing, or researching what I’m writing and editing. I normally work at home a few days per week anyway, and I have a good set of headphones for when I’m in the office.

Only 10% of my day is spent interacting with colleagues. Mostly sprint reviews or sprint planning meetings (I work in an Agile shop) where I provide a quick, 5-minute update on my works-in-progress. These are done through video conferencing, given our dev teams are spread across the globe.

Most other communication happens in chat.

What is a technical writer?

I’ve been doing the technical writing thing since 1995, and I’ve learned a thing or two:

Good technical writers are empathetic, curious, and know how to pester engineers without pissing them off.

You don’t need a “technical writing degree” to be a technical writer. Most come to it from other professions anyway.

Technical writing is not as boring as formatting a phone book. Nor is it as poetic as writing haikus. But even a phone book can be delivered poetically by a good writer.

Most of the time I feel like I know nothing. It’s what drives me to dive deep into each new writing project, figure it out, and then pass on what I’ve learned to someone who has the same questions I once had.

Software tools come and go. Learn how to give an audience the content they need at the moment they need it, and you’ll have a long career.

But knowing software tools helps. Resume bots love ’em.

That’s all for now. More to come.