Skip to Main Content
MIT Libraries Staff Web

PSDocs Style Guide: Organizing content effectively

Style Guide for Public Services Documentation

Buttons

Use the text on the button to refer to it (rather than including an image of the button).
Capitalize the button name and make it bold; do not use quotes.

No: Yes:

Do not use descriptive sentences when describing an action, e.g. "Click the Change Date button" 

Do not use "Hit": e.g., "Hit the patron name"

Use "Click Change Date"

Use "Click," "Enter," or "Select": e.g., "Click Help" or "Select the patron name"

 

Tables

Arrange tables so users scan down rather than across.

  • If a table requires vertical scrolling, consider regrouping content to make the table into logical smaller tables.
  • If you embed images, keep them small but not so small that the images are ineffective.

Back to top

Graphics and Images

Be selective in the use and scope of screenshots; keep the visual clutter to a minimum.  Screenshots require more effort to update and require more experienced users to scroll.

No: Yes:

Do not include a screenshot of an entire window if you need to show only a small part of it.

Crop or resize an image to focus on the relevant sections. Use an image editor (SnagIt works fine) to scale images to no wider than 600 px. or use the Gallery macro to create image popups

Do not use arrows to call attention to an area.

Do use a red rectangle to draw attention to an area. For additional emphasis use highlighter yellow to color the box.

Do not use bubble captions to repeat or replace written steps outside of the graphic/image.

Do put any descriptive (callout) text in red.


Back to top

Links

  • When linking to other wiki pages (including PSDocs, departmental wikis, etc.), use the Wiki Markup link instead of the Tiny link or the link from the browser address bar.
    • Using the Wiki Markup link will prevent the upward-pointing green arrow from displaying.
    • The upward-pointing arrow should only appear to indicate a link to external, non-wiki content (e.g., the Libraries website and/or Libstaff).
  • Put a list of links to related PSDocs pages and/or pages on the Libraries' public site at the bottom of the page.
  • For links to information on the MIT Libraries website, indicate how to reach that page from the MIT Libraries home page. For example:
    • Fine Appeal Form (Libraries home page > Circulation FAQ > Fines + Damaged Materials > Can I appeal a fine? > Fine Appeal Form)
    • This information is helpful when directing patrons to information on our site in person or over the phone.

Back to top

Lists

Use lists to make text more scannable.

  • Use bulleted lists where the entries in the list are of the same importance and/or need not occur sequentially.
  • Use numbered lists where the entries in the list 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.
    • Use a modular approach and link to other PSDocs pages in the text instead of repeating already documented procedures. For example, in procedures for putting an item on search in which the user needs to look up an item record in Aleph, provide a link to instructions on looking up an item record in Aleph rather than repeating instructions on searching in Aleph.

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.