🚧 Under Construction
This page is still being developed. Contact us with any questions or feedback.
MSU Documentation Style Guide
Table of contents
- Acronyms
- Capitalization
- Structure
- Titles & Headers
- Periods
- Referencing Interface Text
- Notes
- Table of Contents
- Links to Protected Documents
- Language
- 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
- Use Chicago Manual of Style Title Case for page title and headers
- Use
&
forand
unless theand
is part of an official name or is interface text
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
Links to Protected Documents
- 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
- NYPL Writing Style Guide 🔒 for general guidelines for the creation of materials online or in print, about or on behalf of the Library