T&D Style Guide

(specifically for the 2005 InDesign print template, but generally applicable elsewhere)

Text

The official dictionary of terms as used by CSM is also online. (Changes to the terminology guide should be channeled through Jeff or Beth.) The training side of the house also has a Style Guide for Procedures.

Section Header corner boxes

Only top level entries (in TOC) can have corner boxes.

Section header boxes typically appear only on the first page of section (either right or left page). When deemed appropriate, use section header continued box on all pages after first page of section.

Use different colored box to distinguish between comparable, typically mutually-exclusive sections (like Win / Mac).

Sideboxes

Try to make first line a title (using title style). Second best: Significant words at the beginning of a sentence (using title style).

Use our basic icons in sideboxes when it helps. Align them towards the outer edge of the page.

Sideboxes can be extended further into body of page, for example, to keep a URL from breaking

URL formats

If address works with www, include them.

www.thingy.com (not thingy.com even if thingy.com would work)

If address does not include www, include http:// if you think it will be clearer. Since our readers are getting savvier, this is less useful than it used to be.

http://uportal.cornell.edu (not uportal.cornell.edu )

If address is at the domain level, leave off trailing slash.

www.cnn.com (not www.cnn.com/ )

If address includes one or more directory, include trailing slash.

www.thingy.com/donut/

If the address includes a file name, include it (duh).

www.thingy.com/donut/jelly.html

URLS should never ever break across two lines. Unless they have to.

Whenever possible, construct your sentences so that there is no punctuation immediately adjacent to the URL.

Wherever we have control over file and directory names, always use lowercase letters.

Key styles (as shown in LIC)

indicates a web address (URL)

Use this style for URLs and for e-mail addresses when the address is referred to as a resource, for example, "Contact support at helpdesk@cornell.edu if you can't install the software."

If an e-mail address is included in step-by-step instructions, then you're telling them what to type, so you'd use the what-to-type style.

indicates a screen button for you to click

This applies to text that appears on a button on the screen (like Next or OK), not to the action you take (like select or click or check)

If the thing that gets clicked has no text (for example, an arrow), use a screenshot of the thing. Any text reference to the thing (for example, click on the arrow to continue) does not use the style

When talking about a thing you click, say "Click Next" - not "Click on the Next button."

indicates something for you to type

Text appearing in this style should appear exactly as we expect the user to type it.

Do not use this style when referring to the field name (for example, do not say "Type your NetID and password into the boxes."

Wherever possible, do not break this text across lines or pages.

Paths and filenames (usually) use this style.

indicates a label on the screen

This is used with any words that serve as identifiers or markers. Examples include window titles, column headings, labels on checkboxes or radio buttons, and icon names.

This also includes things which have a name but are never labelled with that name, like the task bar or system tray.

other text styles (not in the LIC key)

When referring to keys on the keyboard, use bold. If surrounding style is already bold, un-bold the key reference. User discretion.

We don't have a set style for referring to another section in the same publication or referring to another of our publications. Some folks use quotation marks. Let's think about this.

Do not apply styles to actions (like right click or drag). Feel free to break this rule if it makes things clearer.

Table of Contents

All Section Headers and Big Color Headers should appear in TOC.

Black subheads used with discretion (level 3 entry) in TOC.

TOC entries need not exactly match the wording, abbreviations, etc. of the section they refer to. Make them easy to use.

Other (text)

Don't abbreviate (days of the week, months, etc.) unless ab. nec.

Don't use Latin when English will do, e.g., like this. If you mean for example, say for example. If space is tight, use Ex: instead

Sanitize all data - no real NetIDs, names, etc. Use ewe2 as standard single NetID - Ezra W. Erwin and Ethel W. Erwin. If you need to use several NetIDs, make sure that you do not use real ones; use the Electronic Directory to check.

Don't use "contact the Contact Center" if you can avoid it. Use call / e-mail / visit when you only list one method of contacting them.

After last element of a section, before next heading style (Section Header, Big Color Header, or Black Subhead), insert an additional line break in Main Copy style.

Page numbering: TOC page counts as page one, but visible page numbering begins on page two. This is accomplished in InDesign by making the TOC the first page of a new section.

If text uses a character style (like the name of a window) there is no reason to set it off with quotation marks. Save quotation marks for times when there is no appropriate style to use, but you want to distinguish the word or words from the rest of the sentence.

Avoid using "this link" or "this page" as link text. Use a sentence like "See our Connecting to Campus page for instructions." Note that "page" is not part of the linked text.

Screenshots and Images (examples)

General

Use TIFFs for print documents, GIFs for web pages.

Browser windows: include only content of main window (no toolbars, status bar, etc.) unless context is somehow important. If so, hide all but necessary toolbars.

Sanitize the data, even if it seems innocuous. Sanitize your own data, even if you don't care. Either substitute dummy information or blur it.

Resizing

Where possible, move elements closer together rather than resizing.

If resizing is necessary, use Photoshop (not Snag-it or InDesign) to resize.

Edges

When showing a complete window or dialog box, use Snag-it's drop shadow.

(50 pixels; dark gray (the 4th swatch on the bottom row [ R;128 G:128 B:128 ] )

When entire window is not needed, use Snag-it's torn edge feature

(size 1; shadow 30 pixels, same gray), usually on bottom and/or left of shot. In any case, don't use torn edge on all four sides.

Use one pixel border (same gray) to help delineate edges without natural borders.

Annotation

Whenever possible, have annotations extend off the edge of the screenshot (including off the edge of the shadow), to make it as obvious as possible that the annotations are not part of what the user will see on-screen.

Use arrow to point to an element. Align both ends of multiple arrows when possible. Use arrows at consistent angle throughout a given piece.

Use oval to indicate an area. Can also use rounded rectangle, but be sure it doesn't look like a screen element. Do not try to match shape of annotation to shape of screen element.

Use a single color for all annotations in a deliverable, preferably a color not used in the product being documented.

Line weight of arrows, ovals, and step numbers should be similar.

For numbers, use font and approximate size of step number style, and same color for numbering or labeling as for arrows and ovals. Align & consistently space labels where possible.

Do not put title on screenshot; use placement to tie it to text. Exception: related (comparative) screenshots placed together, for example, a Mac dialog and a Windows dialog, or Reply icon and Reply All icon. When labelling screenshots, use Conduit Medium 10pt.

Placement with text

Icons and elements small enough to not affect line spacing can appear inline. Put icon after words refering to icon.

If the icon messes up the line spacing, wrap text around it (print) or use a table (web). Icons should appear as close to text reference as possible.

Elements can be placed with word wrap if the result is not too crowded. Elements placed this way should break the text margin into the white space.

Elements placed with word wrap should align with the top of the text (typically the paragraph) that belongs with the element.

Larger elements should have one blank line (Main Copy style) above and below.

Callout as in example (original area of interest in dashed-line selection box, gray expansion lines)

Suggestions/complaints/questions/bribes go to Jeff.

Last modified: May 25, 2007