Style Guides and Documentation at CDL

This web page has a dual purpose: to provide a consolidated source for CDL staff needing style guides for report or web writing, and to support those writing technical documentation alone or with the help of CDL's technical writer. It consolidates references to the style guides used at the California Digital Library and gives an overview of CDL technical documentation standards and processes, with examples of documentation to make the process easier.

Style Guides

CDL Style Guides

CDL Glossary: A searchable reference of grammar, punctuation, and approved official names and of the UCOP-preferred terms that gives definitions and usage for terms and acronyms used at CDL [HTML].

CDL Website Style Guide: The web style guide for the CDL Brochure site and Inside CDL sites [DOC].

A-Z CDL Style Guide: A guide to usage for CDL-specific terms and style conventions for CDL websites [DOC].

Instructions for Using FrameMaker: A CDL-specific guide to FrameMaker templates and standards. FrameMaker is the documentation tool used by the technical writer for documents published in PDF format [PDF].

UCOP Style Guides

UCOP Stylebook: A searchable, A-Z general reference on style at UCOP. Along with UCOP-specific style guidance, the Stylebook provides references to standard style guides [HTML].

University of California Graphic Identity Guide and Resources: A site that offers downloads and usage guidance for UC symbols such as the UC seal [HTML].

General Style Guides

The style manuals listed here are standard references for U.S. English publications. They provide guidance on grammar, punctuation, structure, and other thorny matters.

• The Associated Press Stylebook: A primary style and usage guide for U.S. journalism, widely available.
• The Chicago Manual of Style, 15th ed.: A primary usage and formatting guide in U.S. publishing, also widely available.
• Read Me First! A Style Guide for the Computer Industry: Thoughtful and well-organized documentation advice from Sun Technical Communications.
• Microsoft Manual of Style for Technical Publications: Widely accepted standard technical manual.

Technical Writing Processes

For the benefit of CDL projects that produce technical documents, this section outlines procedures for getting documentation support, and lists some of the types of technical documents produced at CDL, giving examples.

Documentation Procedures

To request documentation, start by meeting with the CDL technical writer to discuss:

• Project information for documentation: Meet with the technical writer to establish your project's documentation needs, and to present project information via personal interview and project-related documents.
• Review process: Develop a timeline for drafts, reviews, and the final document. The reviewers should include the project or program manager, technical staff, and others as determined by the project manager.
• Final approval: Determine who will formally approve the final draft for publication.
• Publication: Determine the desired format and publication date for the document.

Types of Documents

The CDL publishes documents in a range of formats to fit a range of purposes.

Service document: An internal document documenting a new service in the Common Framework. Example: CDL Template for Documenting a Service [DOC].

API document: A guide for using the programmable functions of an application user interface. Example: The Java Toolkit Developer's Guide [PDF].

Cookbook: A document that describes how to create a service or interface, using existing examples.

Report: Periodical reports on CDL activities for publication and for funding agencies. Example:

Overview or technical overview: An introductory guide to a service or program. Example: Overview of the UC Libraries Digital Preservation Repository [PDF].

Task document: A user guide or walkthrough that explains the decisions steps involved in a specific task. Example: The Preparing to Submit Objects to the Digital Preservation Repository [PDF], which describes how a library prepares digital objects for archiving in the Digital Preservation Repository.