MSU Documentation Style Guide

Table of contents

  1. Acronyms
  2. Capitalization
  3. Structure
  4. Titles & Headers
  5. Periods
  6. Referencing Interface Text
  7. Notes
  8. Table of Contents
  9. Links to Protected Documents
  10. Language
  11. See Also

Acronyms

  • Always write out the first time a name appears on a page with acronym in brackets, e.g. Metadata Management System (MMS)`
  • Subsequent references in the same page can use acronym, e.g. MMS

Capitalization

  • Use Chicago Manual of Style Title Case for page title and headers
  • Use sentence case for body text, bullet points, and notes
  • Avoid all caps unless an acronym (some text element’s styles such as its “Heading 4” are made all caps by Just the Docs style sheet)

Structure

  • Use bulleted and numbered lists with each statement its own line
  • Avoid multi-sentence paragraphs except in notes and narrative text (such as the Projects page)
  • If there are links to other relevant resources either within metadata-documentation or beyond, include a “See Also” section with each link as its own bullet point, e.g. See Also Metadata Liaisons and Contacts 🔒 for a complete list of research library division acronyms and names

Titles & Headers

Periods

  • Avoid use of periods except in notes and narrative text (such as the Projects page), try to separate out sentences with bullet points

Referencing Interface Text

  • When writing out steps of interacting with an interface and referring to specific text that is part of an interface, bold the exact text, i.e. “Click OK to proceed” if the button on the interface says “OK”

Notes

  • Use Just the Doc’s callout feature for note formatting, which can be more narrative/provide additional context and contain multiple sentences with periods; keep these simple

Table of Contents

  • Use page table of contents when 2 or more sections
  • If a page, generally avoid adding text beyond a sentence at the top otherwise TOC gets buried
  • If linked to a document such as in Google Drive or Lair that are not publicly accessible, append the link’s label with a 🔒

Language

  • When referring to MSU, use “we,” “us,” “our,” etc.; e.g. “contact us,” “our preferred link structure is…,” “we recommend”
  • When referring to NYPL, say “the Library”

See Also