Conversation starters

Asking your SMEs or product owners for information to populate a user guide and then waiting for that information is a sure fire way to never completing said user guide (unless you’re among the lucky tech writers to have SMEs/product owners who enjoy writing user documentation).

Instead, research the product and then write a first draft to the best of your understanding, even if it’s just headers. First drafts don’t have to be perfect. Send your SMEs/product owners that draft and ask them what you’re missing.

It’s far easier to critique than create.

Empathy

Technical writers are pain relievers.

In most cases it’s not physical pain. It’s the pain your audience feels when they don’t know how to complete a task, or when they’re trying to figure out why the app isn’t working the way it’s supposed to. Users just want to get their job done and go home, but they can’t because the #$%@! software isn’t working.

Pain.

Good technical writers figure out their audience’s pain and provide the information needed to relieve it.

How do you figure out your audience’s pain? Talk to your product support teams. They can tell you stories…

Jack of all trades

I was planning a post on the non-writing skills of a good technical writer, but Tom Johnson at IdRatherBeWriting.com beat me to it:

How is the role of the technical writer evolving? It seems we’re moving away from writing and more towards other roles, such as reviewer/convener, user champion, editor, publisher, and promoter. However, it’s difficult to gauge change, especially across different job categories. In some scenarios, writing might never have been why we were hired.

Read the whole thing.

I’d say 3/4 of my day-to-day job is spent on non-writing tasks. Employable technical writers always have been (and always will be) flexible and seek ways to add value to the organization where ever they can.

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

Leave a comment

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?

Leave a comment

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.