Using “recommends” in tech docs

In our Write the Docs Slack network, a member asked if we knew of any best practices on using the word “recommend” in technical documents. There are no official best practices, so we all had different suggestions, such as:

  • Use sparingly, but when you do, state why you’re recommending it so users can decide if it makes sense for them.
  • If the recommendation is brief, use it within a special notice. For example, “Note: [Company] recommends X because…”
  • If documenting hardware and software requirements, place the minimum and recommended requirements into tables to make information easier to find and scan, especially if there are different deployment options.

All these suggestions make sense, depending on the type of document, user, and product. The main agreement is that we shouldn’t use “recommend” too much, but when we do, provide context and make sure it’s noticeable and neat.