Help document is important


I make lots of services, software all the time. Instead of making private specification documents for clients or the internal teams, why not have a great help document where people just go there and get to know how to operate the software.

So where to start?

How to start

  1. Let's start by writing out roles. Tell me who will be using the software and what they will do with the software.
  2. Let's write out the "Get Started" document for each role. Write out the quickest way to start using the software.
  3. Let's write out the user flow of the software and then list out features for each flow. I write out the flow first to make sure I cover all use cases.
  4. Let's list out features, functions of the software. I do #3 first to make sure all user flow is covered, then I know that features and functions will overwrap. You don't have to write duplicate or almost duplicate content. The list of features and functions may overwrap across flows but can link them to the one feature function explanation page.
  5. At the end you write FAQ pages to guide you to the proper help page.

After managing and operating the FAQ page, you may want to make revisions to the help pages.

What to include

Make sure you include the date that is published and the applicable software version. When you operate this document for a long time, and the software may have upgrade and changes, you want to hint user that is an old help page and may not be applicable to the current version. Of course, it is the best practice to not have such cases, but you know.

  • title
  • short description
  • applicable software version
  • publish date
  • how long it will take to read it
  • content
  • related FAQ or related contents (in case this content was not what they were looking for and still want to resolve the issue)
Published: 2021-08-29