SILS documentation site style guide

Before you begin:

The SILS Staff Documentation Site resides in the Library Staff web and is available for anyone to view and any UC Berkeley staff member to edit, given they complete training from representative(s) in their SILS functional area and review the SILS Documentation - Drupal Staff Web maintenance instructions to learn how to edit the site. The login to edit documents is behind CalNet authentication and authorization is granted by the Library Web Team.

The SILS documentation site style guide is a supplement to the web maintenance instructions.

The SILS Documentation Site Task Force developed a set of best practices to guide staff in the creation and maintenance of documents to accomplish the following:

• Allow for transparency in process to facilitate the use of editing practices by staff across the organization in the spirit of democratized system management
• Share knowledge freely across the Library to align processes and practices
• Provide guidelines to promote consistency across documents in different functional areas, created at different times by different staff members
• Foreground accessibility in all documents and training resources

Definition of terms in the style guide

• Accessibility: According to W3C, “web accessibility means that websites, tools, and technologies are designed and developed so that people with disabilities can use them.” Accessibility also benefits individuals without disabilities and provides greater access to the web for everyone.
• Body summary: A field in the Drupal template editor which allows you to type a brief description of the SILS document. The brief description will display on a Search results page and in the Pages section of a landing page.
• Drupal: Drupal is the open-source content management system that the SILS staff documentation site uses.
• Related documentation: In the content page template in Drupal, it is possible to include links to related resources which display on the right-hand side of the page. Content creators and editors are encouraged to include related documentation when applicable for documents which may be beneficial to the user.
• Sentence case: This style requires that the first word in a sentence is capitalized in addition to any proper nouns. Sentence case should be used for document titles, and is in alignment with the Library Communications Office.
• Tags: Tags allow users to group like documents together across functional areas; tags facilitate access to documents beyond keyword searching and browsing by individual functional area on the site.
• Template: The Library Web Team created templates in Drupal to create a consistent look and feel in the SILS documentation site. It is not possible for SILS site editors to change the template.

Checklist

See below for a checklist of elements which should be included in (almost) every document on the SILS documentation site. Check out the template page on the Drupal site for a visual idea of how to structure a content page.

• Title
• Brief description of the document at the top of the page (use text as the body summary)
• Public Services impact statement
  • Address how this process/workflow/configuration will impact end users
• Alma roles required to complete task(s)
  • If you don’t know, consult with the SILS functional area lead to get this information
• Update URL alias to include the appropriate functional area
• Body text
• Add related documentation, when applicable
• Add relevant tags to the document

Formatting documents

Pages are based on a hard-coded template which will allow you to create a page according to accessibility standards and to harmonize fonts, formats, and “look and feel.” You only need to add content. To view/edit HTML, you can click on the “source” button. Otherwise, you can use the rich text editor.

• Tables have specific formatting guidelines within the Drupal template and are to be used to present data in a tabular format rather than a style choice.
• Use sentence case capitalization for document titles
• Include a body summary for each page
• Remove underline for all hyperlinks
  • When documents are pasted from Google docs into the Drupal template editor, an added underline is added to hyperlinks
• You may need to delete extra spaces between paragraphs
  • When documents are pasted from Google docs into the Drupal template editor, extra spaces are sometimes inserted between paragraphs
• Do not rely on visual formatting, including bold and italicized text, to convey emphasis. Bold and italicized text is not conveyed on screen readers, and is less easy to read than regular text. Use words and formatting within the template (e.g. headers, and tables for tabular data) to emphasize and convey meaning rather than text formatting. 
• Use the pre-defined text color(s) in the Drupal template rather than making adjustments in the source code.
• It is important to nest headings correctly within documents. The title of the page is Heading 1, and the first section of a page will be Heading 2. Heading 3 must follow Heading 2. This allows the document to be correctly formatted and is crucial for screen readers.
• Videos can either be embedded within the page, or you may link out to a separate site. Video uploading and embedding can be a bit tricky. Please see the detailed video instructions.
• Ordered lists are to be used when steps must be performed sequentially, and unordered lists are to be used when the order of the elements does not matter. Further information can be found in the W3C tutorial on content structure.
• Avoid references to Millennium unless needed
• If a link to a video or resource is restricted to UC Berkeley users, follow the URL with (UC Berkeley only)
• Do not include revision history. The revision history is tracked through Drupal. For substantive changes, send an email announcement outlining the changes.

Guide to SILS documentation site tags

Tags allow users to group like documents together across functional areas; tags facilitate access to documents beyond keyword searching and browsing by individual functional area on the site. When creating, editing, or updating a document, all relevant tags should be reviewed and selected. 

Types of documents (highly recommended)

• Configuration: Alma system configurations related to administrative roles or integrated third party software set-up instructions or informational documentation.
• Policy: Guidelines used for the basis of making or supporting decisions and achieving outcomes (for example procedures or protocols).
• Procedure: A document that includes step-by-step instructions for a process.
• Required training (for role authorization): Training needed to receive Alma role authorization, rather than just a helpful resource.
• Supplemental training: Content which provides additional training information beyond that which is required for role assignment.
• Workflow: A document that outlines a process.

Departments and groups (include, if applicable)

• Affiliated libraries
• Bancroft
• Discovery Working Group: A document created or maintained by Discovery Working Group (DWG).
• East Asian Library (EAL)
• Fulfillment/Resource Sharing Working Group: A document created or maintained by Fulfillment/Resource Sharing Working Group (FRSWG).
• Item Records Task Force: A document created or maintained by Item Records Task Force (IRTF).
• Library Business Services (LBS) 
• Metadata Services: A document created by or specific to Metadata Services.
• Northern Regional Library Facility (NRLF)
• Resource Management Group: A document created or maintained by Resource Management Group (RMG).

Functions (highly recommended)

• API: API stands for Application Programming Interface. An API is a set of rules which allows one software application to communicate with another software application.
• Cataloging: A document for describing and providing discovery of library resources. Includes resource description, subject analysis, classification, and authority control.
• Circulation 
• Collection maintenance: A document that discusses post-cataloging updates to bibliographic, holdings, or item records for processes such as withdrawals, transfers or relocations, replacements, binding, and preservation.
• Invoicing (Acq. function)
• Ordering/Purchase orders (Acq. function)
• Physical processing: A document that discusses the marking and physical processing of library materials. Includes affixing barcodes, printing and affixing spine labels, applying tattle tape, stamping with property stamp, and preservation processes and enclosures.
• Receiving (Acq. function)
• UC Library Search: A document which discusses the branded name for the UC implementation of Primo VE. UC Library Search is a discovery layer which includes UC Berkeley physical and electronic holdings, UC campus holdings, electronic resources through the Central Discovery Index (CDI), and WorldCat.
• User experience: A document related to how a user interacts with or uses UC Library Search. Accessibility is a core concept in the usability of the UC Library Search 
• Work order: A document which uses or references a work order in Alma. A work order is an internal library request to route physical materials to a specific department for internal processing, per ExL documentation.

Key/relevant topics

• Import profiles: A document which uses or references an import profile in Alma. Import profiles are used to import multiple records in bulk and define how the records should be imported. For more information, see ExLibris documentation. 
• Normalization: A document which uses or references a normalization rule or normalization process. 
• OCLC Connexion: A document that discusses how to configure and use OCLC Connexion Client. For documents that discuss what to enter into OCLC records, use Cataloging.
• Shared Print: A document related to the building or maintenance of a collaborative shared print archive.
• WorldCat (Discovery): A document which references the WorldCat Profile in UC Library Search.

Accessibility considerations

• Add “alt text” to all screenshots and images included in the documentation
  • Add image in document to library in Drupal, then add the image to document and add alt text
  • You may also choose to update the source HTML to add alt text
• Use written instructions instead of screenshots when possible. Screenshots may be used to illustrate the instructions when necessary.
• All embedded videos must contain captions. 
  • Link to how to add an embedded video
  • Link to how to merge caption and video files
• Avoid using too many acronyms or abbreviations. Write out the full content first and add acronym in parenthesis following. 
• Reduce jargon as much as possible
• Ensure that if "bold" text is used, the <strong> HTML tag is used rather than a <b> HTML tag.