How to write for applications consistently and with clarity

When you’re writing within Redgate products, or for release notes or support documentation, consistency is key. It means when a user moves from SQL Prompt to SQL Source Control, for example, everything will be familiar.

The language will be just as clear and succinct. The way commands are used, spelled, and capitalized will be the same. Finding, reading, and understanding release notes and software documentation will be easy.

Achieving that level of uniformity isn’t about having a set of rigid guidelines that tie you down. It’s about setting the parameters within which you write so that boring questions disappear, like whether or not to capitalize buttons, how to structure release notes, or how to use links within text.

Leaving you to think about the interesting stuff: the writing.

The short version

  • Use plain English
  • Delete every word you don’t need
  • Use American English, unless you’re writing exclusively for the British market
  • Use capital letters cautiously. You Don’t Need To Capitalize Everything Like This. The same applies for buttons, headings, and menus.
  • It’s fine to use contractions (eg, it's, isn't, hasn't, etc)

Style

For technical writing at Redgate, we generally follow the gov.uk style guide, which says: Write conversationally – picture your audience and write as if you were talking to them one-to-one but with the authority of someone who can actively help. The content you write should be:

  • Informative
  • Clear and concise
  • Brisk but not terse
  • Incisive yet human (not a faceless machine)
  • Serious but not pompous