Skip to Main Content
MIT Libraries Staff Web

PSDocs Style Guide: Required page elements

Style Guide for Public Services Documentation

Section headings

Section headings make a page more easy to quickly scan, giving a sense of the page's contents.

No: Yes:

Do not create sections when the page is short.   

Use Section Headings to break text heavy pages into logical blocks. Use Section Headings when appropriate to clarify what type of content is in each section - "about," "how to," etc.

Do not use using h1., h5., or h6. heading types.

  • h1. is too large for most monitors
  • h5. and h6. are often smaller than regular text

Use h2., h3., and h4 heading types.

Do not create wordy section headings.

Use concise terminology so that the section headings may be quickly scanned to determine what's in the page.

Do not begin with detailed information.

List general information first, followed by specifics. Staff needing more specific information may click to the appropriate section from the table of contents or jump list.

Do not use inconsistent grammar in headings of the same level: (e.g., "How to Process Faculty Office Delivery Requests" and "Packaging the Request for Delivery").

Use the same grammar structure in headings of the same level (e.g., "Processing Faculty Office Delivery Requests" and "Packaging the Request for Delivery".

Back to top


Start the page with a brief (1-2 sentence) summary of the topic. This summary will help users of the A-Z list.

Back to top

Page titles

Choose a title that best describes the page's content and makes the most sense to other users.

No: Yes:

Do not start a title with an article such as “the” or “a”.

Remember that the first word of the title determines where users will find the page on the A-Z list.

Do not capitalize all words in the title.

Capitalize the first word of the title and any proper names or brands.

Back to top

Table of contents

Tables of Content are important tools for page navigation. Use them on pages that require scrolling.

No: Yes:

Do not manually create a table of contents.

Use the {TOC} macro in the template to create a Table of Contents.

Do not use a table of contents if there are 2 or fewer h2 sections on the page. Create a Table of Contents if there are 3 or more h2 sections on the page.

Do not delete the "jump to top" link  from the template.

Use a "jump to top" anchor at the end of each h2 section to lead users back to the top of the page.

Back to top

Related Links

List links to related PSDocs pages and/or pages on the Libraries' public site at the bottom of each page.

Back to top