Category: writing

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.