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.

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.