Within software applications

Redgate products are ingeniously simple. They solve complicated problems in an apparently easy way and they’re intuitive to use.

That simplicity is reflected in the way we use words within applications. Instructions are succinct and easy to follow. Error messages are concise. The language is uncomplicated, even if what we’re explaining is complex.

The general rule here is to be clear, direct, and informative. Be friendly, not ‘matey’.

There are also certain ways we do things that make moving between Redgate products easier for users because it helps to create a familiar environment.

Button labels, for example, only have the first word capitalized, as in Link to source control.

Checkboxes are selected, not checked, and cleared, not unchecked or deselected.

Dialog box is always used in full, rather than using the abbreviation dialog and titles use sentence case, with only the first word capitalized.

If the product you’re writing within is a plug-in like SQL Prompt, and the dialog box opens in a host application, the name of the tool is also included in the title with an en-dash. For example, SQL Source Control – History.

Ellipses are used in button labels and menu choices where further action is needed from the user.

A button labeled Deploy, for example, indicates the deployment will happen immediately after you click it. (If you need to emphasize this, consider labeling it Deploy now)

A button labeled Deploy..., on the other hand, indicates the button might start a wizard, open a dialog box, or ask what you want to deploy.

On this basis, Send feedback… needs an ellipsis, because it requires further input from the user, but Documentation and Check for updates don’t.

The only exception is that we don't use ellipses for actions that produce warnings or confirmations. For example, a button labeled Delete that produces a warning dialog box asking Are you sure you want to delete this file? should be written without an ellipsis. This action would happen immediately – the application already has all the information it needs to do the job – but we're making extra-sure it's what the user wanted to do first.

In documentation, when referring to a control with an ellipsis in the label, don't include the ellipsis in the text. For example, write Select the objects and click Deploy, not Select the objects and click Deploy...

Error messages are an integral part of the user experience, and users are more annoyed by a bad error message than they are delighted by a well-designed UI. That said, we try to minimize the annoyance factor by following the same steps for every error message:

  • Explain what went wrong, why, and (if possible) how to fix it.
  • Be precise. If the cause is unknown, say so.
  • Be succinct. Users may search Google or our documentation using the error text, or quote it to the support team, so make sure it’s as clear and readable as possible.
  • Link to any relevant documentation.
  • Provide a Close rather than OK button. Having to click OK when an application fails makes the user feel like they’re being held hostage and forced to agree to bad things.
  • Don’t try to be apologetic (Sorry, your data couldn’t be recovered) or funny (Yikes! Where’d your data go?). Keep the tone neutral and stick to the facts.
  • If the message is a warning (something bad might happen if you continue), use a yellow triangle. If it’s an error (something bad already happened), use a red stop icon.
  • Typos give a poor impression of the quality of our tools. Read the message out loud to find mistakes and get someone else to review it.
  • Where is the error message displayed? Is it a separate dialog box or in a GUI? If it’s a separate dialog box, the title should typically contain the name of the application.
  • Would someone who isn’t a developer for this application understand the problem described?