Skip to Main Content
MIT Libraries Staff Web

PSDocs Style Guide: Writing style

Style Guide for Public Services Documentation

Basic writing guidelines

Clarity is key. Too much text can crowd the page and overwhelm the user.

  • Use short, descriptive sentences and paragraphs.
  • Create bulleted lists where possible.
    • Use bullets where the entries in the list are of equal importance and do not follow a sequence.
  • Use numbered lists where the entries must follow a sequence.
    • Use a separate step for each action.
    • If a step involves a number of substeps, consider breaking the procedure into sets of actions.
  • Be careful about hyphen usage: do not over use them.

Be brief

No: Yes:

Do not write: "Make sure you use your Aleph login to log in to Aleph at the beginning of your shift."

 Write: "Log in to Aleph at the beginning of your desk shift."

 

Back to top

Active voice / imperative mood

No: Yes:

Don't write:

  • "X should be clicked"
  • "The X button allows you to Y"
 Write: "Click X"

Back to top

Consistent terminology

No: Yes:

Do not use terms like "Staff Barton"

Use "Aleph" instead "Staff Barton."

Refer to the terminology list for when to use "login" vs. "log in" and other common terms.

 

Back to top

Abbreviations and acronyms

Define acronyms and abbreviations (in parentheses) following their initial use on a page.

No: Yes:

Do not create new acronyms.

Use known acronyms.

Do not use "eg.", "eg", "etc", "ie." or "ie"

Use "e.g." ,"etc.", "i.e."


Back to top

Staff Web | MIT Libraries | MIT

Powered by Springshare. Text licensed under Creative Commons, unless otherwise noted. All other media all rights reserved unless otherwise noted.