Software documentation

Like writing within applications or writing release notes, consistency in software documentation makes it easier to follow, read, and digest. It makes it easier to write too because you don’t need to cast around for the right word to use or the right way to use it.

Software documentation can cover everything from getting started to requirements and supported systems to troubleshooting.

In each case, the broad advice about using plain English and being clear and concise applies, but there are also some broad guidelines we follow to maintain the consistency we aim for.

Bold typefaces, for example, draw the eye and can be used to reinforce task structure. In documentation, we embolden the names of things users will interact with or look for, such as:

  • Buttons
  • Dialog boxes
  • Tabs
  • Panes
  • Text boxes
  • Menus
  • Checkboxes

For example: To compress the backup, select the Compress backup checkbox.

Close is the word to use when closing windows, documents, or dialog boxes. Use exit for programs, and end for network connections.

Do or follow are used rather than perform or execute, unless you’re talking about executing code. For example, Follow the instructions on the Setup page.

Documentation is called that, not help, support, support center, etc. It’s fine to have a Help menu in the tools, but when you link to documentation from there, write Documentation, not Help contents, etc.

Enter is the correct term for fields you type text into. For example: Enter the database name.

Icons can also be helpful when you’re trying to describe an action.

Italics can and should be used for:

  • Things a user can type or specify, as in: ‘Type or select WidgetStaging
  • File names, as in: ‘Open SQLScript.sql in your SQL editor’
  • File paths, as in: ‘Go to C:\Program files\Red Gate\SQL Compare 11
  • New terms to distinguish them from the rest of the sentence, because it will look odd if you don't. As in: ‘Whenever you compare databases, you set up a project

Links within text are important – and it’s important to use them in the correct way. We don’t, for example, use phrases like click here for a link. Ideally, the title of the page you’re linking to will be self-explanatory. In these cases, write See Linking to source control, not Read about linking to source control here.

If the information you're talking about isn't obvious from the page title, explain what information it contains before you link, For example, For more information about how migration scripts work, see the overview. Use the before the link if it makes sense, but don't make it part of the link, and don't capitalize afterwards.

If you're short of space in a UI, it's OK to just write Learn more (without a period). For example, You can change the SQL Compare behavior by editing the comparison options. Learn more

It can be tempting to turn part of the text into a link, as in: You can change the SQL Compare engine behavior by editing the comparison options. In the context of a product rather than a website, however, this might be mistaken as performing an action rather than opening documentation.

Finally, punctuation like periods and commas following the link should never be part of the link text.

Mouse and key actions are capitalized in the same way as most keyboards:

  • click
  • right-click
  • double-click
  • Ctrl
  • Alt
  • Shift
  • Enter
  • Backspace
  • Space (not the space bar)
  • Tab
  • Caps Lock
  • A, B, C etc (for letter keys)
  • F1, F2 etc

Use ‘+’ for simultaneous actions. For example, Highlight the objects with Shift + click or Ctrl + click.

Page titles and headings use sentence case with only the first word capitalized. Subsequent words are all lowercase, except for proper nouns, acronyms, etc.

On documentation page titles, don't specify the product name prior to the title as in: SQL Source Control: Setting up. It's unnecessary, because that page is already in the SQL Source Control space.

For ‘how to’ pages, use statements rather than questions. Creating backups, for example, not How do I create a backup?

For troubleshooting pages about error messages, use the error message (truncated if very long) for the title. Otherwise, state the problem in the present tense in the terms users are most likely to search for. For example, Can't run two database backups at the same time.

The word please can sometimes make writing feel cold. For example, To view source control history, go to the History tab sounds more helpful and neutral than To view source control history, please go to the History tab.

The exception is if we're asking users to do something that principally benefits Redgate and not them. For example,

Although we test updates thoroughly before releasing them, some of the updates on the frequent release channel might not work with your environment. If that happens, please contact Redgate support so we can fix it.

Though it does benefit the user to get their bugs fixed, this example is more about asking users to report bugs so we can do our job better. We're basically asking a favor of them, so please is appropriate.