— Documentation guidelines

Summary: This document provides guidance on the creation and maintenance of the MSU Libraries Technical Services Division's policies and procedures documentation. The guidelines ensure a cohesive presentation for users on the site and assist procedure writers in crafting new procedures. 

Creating a new page

• Use templates in the panel to guide you through adding a new page. Some technical guidelines are included in the templates that aren't mentioned in this document (e.g., adding labels).
  • The Long procedures template automatically generates a table of contents, and should be used for procedures needing multiple steps and substeps.
  • The Short procedures template is suitable for brief sets of instructions that fit on one computer screen.
• Double check that you are not creating content that already exists elsewhere.
• Titles of procedures should be brief and descriptive, saving more detailed information for the summary note.
• Begin every procedure with a summary note that gives users a framework for what to expect in the procedure and providing any relevant context. Summaries should not exceed a couple of sentences in length. 
• Some procedures that have policies that govern the application of that procedure (e.g., call numbers must be unique). Generally, these are policies that are important but not necessarily something readers need every time they read a procedure. (e.g., copy cataloging is generally the purview of LA IIIs).
  • Add applicable information in the ‘Policies’ panel in the sidebar.
  • If there is no applicable information, the 'Policies' panel sidebar should be deleted instead of left blank.
• Use bullet points or tables to make information readable and easily digestible. Add horizontal rules to chunk up info (under the menu + symbol or hit the - key three times).
• Include your name (or the name of the responsible party if you are writing the procedure on someone's behalf) as the contact in the sidebar panel blank for contact. Highlight the name and click on the 'insert link' select 'web link' and add mailto:[and the email address].
•  Add the date of creation in the panel in the right sidebar panel. If you are editing a procedure, be sure to change the updated date.
• Style should be consistent within the procedure and should be consistent with other procedures.
• Consult the list of labels to apply appropriate ones to your document. If appropriate label does not exist in the library, contact the TSDG to get suggest that a new label be created.

Back to top

Keeping content consistent

Follow style guidelines

• Write in concise and plain language, avoiding first person.
• Keep information brief and lean–info presented to users who don’t need it is just noise. Group related ideas together and use descriptive headers and subheaders.
• Prefer active voice over passive voice.
  • Use: Catalog Maintenance will add labels.
  • Not: Labels will be added by Catalog Maintenance.
• Spell out abbreviations the first time they occur in the procedure (except in the case where the abbreviation has replaced or surpassed the original name, like OCLC). Avoid slang and jargon as much as possible.
• Use the date format of: MM-DD-YYYY. When referring to months, write them out and do not abbreviate (January - not Jan.). Always write out the year (2015 - not ‘15)
• Use the serial (Oxford) comma.
• Don’t use excessive bold or italics. Avoid underlining and all caps.
• Refer to job titles when possible instead of individual staff names to defeat the need for excessive updating (e.g. original serials cataloging staff member, Map Cataloger, Assistant Director, etc.) when a person retires or moves on. Try not to describe the location of a shelf/cart or other item using descriptions of individual's offices.
• Use American spellings and refer to the APA (American Psychological Association) Style Guide when formatting issues arise that are not covered in this local style guide.

Format page elements (images, links, etc.)

• Images - feel free to upload images like screenshots or diagrams.
  • ALWAYS use alt text to label all images. Alt text can be added by clicking the image you add to a page and selecting 'properties.'
  • Alt text is especially important in ensuring accessibility. In general, describe the image so individuals who don’t see the image come away with the same info as if they had.
  • Contact the TSDG if you have trouble adding alt text.
• Use sentence case for menu names, procedure titles, and procedure headings (H1)
• Headings and subheadings should organize content for readers and allow them to scan and understand content quickly. Headings (H1) should be used for procedure titles and should give individuals an idea of what they are about to read.
• Subheadings (H2, H2, H3, etc.) should be a hierarchy of information and break groups of information into sections to make the procedure scannable. Subheadings always nest in the hierarchy: H2 follows H1, H3 follows H2, and so on.
• Links - provide a link whenever a reference is made to an external webpage or to another document webpage within the procedures. Do not use phrases such as ‘click here.’ Instead, write the sentence normally and link relevant keywords:
• Use: For subject authority work, catalogers can use the forms available on the SACO page.
• Not: For subject authority work, catalogers can click here to use the forms available on the SACO page.
• Lists - Use lists to present groups or sets of information. Number these lists when the order is important. Don’t use numbers when the order is not important. If the list item is a complete sentence, use punctuation and proper capitalization, otherwise don’t.

Back to top

Keeping content accessible

• The TSDG has built accessibility considerations into the TS templates. If a procedure writer has any questions or encounters an accessibility concern not covered in the template, consult with the TS document group to ensure a procedure has proper accommodations.
• Write for a diverse audience of readers who may be approaching the content in different ways and using different tools.
• Avoid directional language or any language (color, images, formatting) that requires the reader to see the layout or design to understand.
• Use headers - nested and consecutively to group sections together for easy navigation and interpretation of content.
• Tables may be used when they are conveying data. Do not use tables for layout formatting. Data tables have column headers, row headers, or both that relate to the data in the table. Tables used in the TS documentation space must have headers (see templates for more info in adding headers in the Confluence editor).
• Always use alt text on images, including charts and graphs. Images should not be the only method in which something is communicated.
• If uploading a Word document or PDF, these documents should be accessibility compliant. See the MSU Libraries Accessibility Working Group’s guide on document accessibility (MSU web access required).
• When using a video as a part of instruction, closed captioning or transcripts should be made available.
• Use high contrast images and do not change font colors. If you must change the font color, be sure to check for high contrast between the font and background colors using appropriate tools.
• If you have any remaining questions regarding accessibility, contact the TSDG.

Back to top

Revising existing procedures

• Any updates must be made by the content owner, or with the content owner’s permission.
• Ensure information in the summary note and in the 'Policies' panel are still accurate after the changes are made to a procedure.
• Ensure the contact information in the page info panel is still accurate. Update the updated date to the current month.
• When archiving an existing page, provide the date and reason the procedure was archived in the summary at the top of the page. If the procedure contains information or instructions that are no longer to be followed, use the warning macro to warn users that the information is out of date. See procedures currently in — Archive for examples.

Back to top

Organizing pages and navigation

• Menus–including all parents and children pages–will be in alphabetical order, unless a valid case can be made for a different location of a specific page. Top level menu items are the purview of the  TS Documentation Group (TSDG) to ensure cohesive structure.
• Nesting of children under parent pages will not exceed three generations.
• Do not recreate information that is available elsewhere in the documentation; if you need help organizing the information, consult with the TSDG.
• Create pages that offer meaningful choices. Too many choices = more cognitive load and the harder it is for users to make decisions and understand information.
• Labels (Confluence calls tags labels) are available to label procedures and policies for classifying information in different ways. The label library is a closed list. It is maintained by the task force. Definitions of labels may be found in the glossary. To suggest a new label, contact the TSDG at tsconfluence@lib.msu.edu. 

Back to top

Oversight of the entire space

• Every procedure has a content owner responsible for the procedure, either as drafter of said procedure or as manager of the unit to whom the procedure chiefly applies. Each procedure will undergo an annual review by its content owner(s).
• Top-level navigation menu items are edited/added to only by the TSDG. This is to ensure a cohesive space.
• Pages may be restricted so that only the owner of that page may edit it.
• The TSDG will maintain a spreadsheet of procedures and their dates of review. Content owners will be contacted within the month their procedure(s) is due for review by the group.
• The TSDG will consist of three members, all of whom have site admin access to Confluence and the TS procedures and policies.
• The group is also available to give feedback or to advise on all TS Documentation matters.

Back to top