Common Style Problems Speaker: Roshni Kamath Date: 23-Sep-2013 1

Common Style Problems

Speaker: Roshni Kamath

Date: 23-Sep-2013

1

Agenda

• What is a style guide• Why Style guides are necessary• Common Style Problems

• Procedures• Dates• Capitalization• Measurements and Units of Measure• Numbers• Protocols• Names of Special Characters• Telephone Numbers• Time Zones• URLs, Addresses• Company with Product Names• Version Identifiers• Readme Files and Release Notes• Bibliographies• Titles of Publications

• MSTP vs. Chicago Manual : Comparison

2

What is a style guide

A style guide provides a means of documenting basic rules or features that ensure consistency in the output.

A style guide or style manual is a set of standards for the writing and design of documents, either for general use or for a specific publication, organization or field.

3

Why Style guides are necessary

4

The implementation of a style guide provides uniformity in style and formatting within a document and across multiple documents

Some organizations produce style guides for either internal or external use

It is best to ascertain which guide your client prefers you to use, because there is often a “house style” to be aware of


5

Procedures

When you want the user to Use this syntax

Select an option In the Print dialog box, click All.

Open a tabbed section in a dialog box In the Font dialog box, click Character Spacing

Insert text in a combo box In the File name box, enter the name of the file.

Select multiple check boxes On the Print tab, select the Comments and Hidden text check boxes

Select items in a group box Under Include with document, selectthe Comments check box.

• Steps in a procedure or task follow the navigational structure of the application left to right, top-down. Each step must include the menu commands, or dialog box and field names in the sentence.

• The top-down method determines the "big picture" (global view) of the application first and then defines its features in detail.


6

Dates

STYLE in MSTP STYLE in Chicago Style guide

The February 23, 2001, issue of the New York Times

May 26, 2008, was a sad day for film buffs.

The February 2001 issue of MSDN Magazine

the 1980s and ’90s

Incorrect23 February 20006/11/9911/6/99April 21st

- no difference -


7

Capitalization

Examples from MSTP Examples from CISCO Style guide

Click the Insert Table button. Call the Cisco Technical Assistance Center.

How to Format Your Hard Disk Setting Up the RADIUS Profile for Two-Way Authentication

Press the LEFT ARROW key. Ampersand key , the Ctrl-C key combination.

* Use sentence-style capitalization for UI specific element.

* In a Warning, the word on or off appears in uppercase (ON or OFF)

• Title-Capitalization: First letter of each word is a capital letter• Sentence-Capitalization: First letter of a sentence and proper nouns are capital • Headings: Follow rules as per project template or your organization style guide* When NOT to: Do not overuse capitalization. Never use all uppercase for emphasis.


8

Measurements and Units of Measure

STYLE in MSTP STYLE in CISCO Style guide

• Do not insert periods after abbreviations of measurements except for in. (inch).

• Use the multiplication sign (×), not by, to specify screen resolutions

• Do not abbreviate units of measure except for kilobytes (KB), megabytes(MB), and gigabytes

(GB)

• Use an en dash for all ranges except in indexes, text, and figures.

• Spell out all occurrences of micro as symbol μ) does not always appear correctly online

• Use the same unit-of-measure abbreviation for all quantities

5 inches or 5 in.0.5 inch, 0 inches8 bits12 points highsix 1/2-inch cables

1 MB, 12 MB0.5 kg, 1 kg, 5 kg1 cm, 6.5 cm1 ms, 200 ms56 to 64 kbps; 56–64 kbps


9

Numbers

When you want the user to Use this syntax

• Use numerals for 10 and greater. • Spell out zero through nine if the number does not

precede a unit of measure or is not used as input.• Use numerals for all measurements, even if the

number is less than 10.• Use numerals for coordinates in tables or

worksheets• Use numerals in dimensions.• Use numerals to indicate the time of day.

0 inches ; 3 feet, 5 inches0.75 gram35mm camera8 bits1-byte error valueChapter 10, row 3, column 400:01 (1 minute past midnight)

• Use an en dash, not a hyphen, to form negative numbers. Use en dash in ranges

• Hyphenate compound numbers when they are spelled out.

–79 ; 10 – 9 = 1© 1993–1994pages 95–110Twenty-five fonts are included


10

Protocols A protocol is a standard for communication between

computers Most protocols are referred to by their abbreviationso Example: Internet Explorer supports Hypertext Transfer Protocol (HTTP).

In URLs, the protocol used by the Web server appears in lowercase before a colon

o Example: http://www.google.co.in


12

Telephone Numbers


For U.S. telephone numbers, use parentheses, not a hyphen, to separate the area code from the seven-digit phone number.

(425) 555-0150

Inside the USA and Canada, Use the format: Area code (space) group of first three numbers (hyphen) group of last four numbersEXAMPLE Cisco Systems, Inc.,

Americas Headquarters, 408 526-4000Do not include the access code for international long distance in phone lists.Do not put a plus sign (+) in front of a phone number.

(44) (71) 0000 000 0000 [U.K.]

Outside the USA and Canada, Use the format: First group of numbers (space) second group of numbers (space) third group of numbers (space), and so forth. Do not use hyphens to separate these numbers.EXAMPLE Cisco Systems,

European Headquarters, 33 1 6918 61 00


13

Time Zones

STYLE in MSTP STYLE in Chicago Style guide

The names of time zones should be treated as proper nouns. A time zoneis a geographical area.

• When spelled out, designations of time and time zones are lowercased (except for proper nouns).

• Abbreviations are capitalized.• EXAMPLE: Please attend a

meeting in Grand Rapids, Michigan, on December 5 at 10:30 a.m. (EST)

• GMT : Greenwich mean time• EST : eastern standard time• PDT : Pacific daylight time

The current internationally accepted

name for Greenwich Mean Time is

Coordinated Universal Time (UTC).

EXAMPLES:The show begins at 19:00 Pacific Time (UTC-8).Eastern Time (UTC+10) (Australia)


14

URLs, Addresses A uniform resource locator, or URL is designed to lead a reader

directly to an Internet or intranet source. A URL consists of an Internet protocol name; a domain name;

and optionally other elements such as a port, directory, and file name.

Each of these main elements is in lowercase type, unless case is important.

URLs often appear at the end of a sentenceo Examples:

http://www.microsoft.com/business/

ftp://www.example.com/downloads/myfile.txt

mailto:[email protected]://preview.cisco.com/en/US/docs/general/style/guide/latest/sg.html


15

Company with Product Names


On first mention, always precede the name of a product with the company name

Brand names that are trademarks should be capitalized if they must be used.

Examples:

Microsoft Windows XP, Windows 2000, and Windows NT 4.0Windows NT version 3.1 or later

Trademark is the legal word for a name given to a product or service

In technical documentation, do not use any

trademark symbols with the Cisco name.

Examples:

The Cisco IOS software provides many performance benefits.


16

Version Identifiers Product and product component names can include version

information by special identifier o Examples: by year of release (Windows 2000), or by chronological version

number (Windows NT 4.0).

When listing different versions of a product, list the most recent version first.

o Examples: Microsoft Windows XP, Windows 2000, and Windows NT 4.0

A complete product version number has three components:• Major release identifier: X.x.x• Minor release identifier: x.X.x• Update identifier: x.x.X

o Examples:Internet Explorer 4.0Microsoft Exchange Server 4.0.829


17

Readme Files and Release Notes Readme files provide up-to-the-minute information about a

newly released product. Release notes provide information about test and beta releases You can use the term readme file or readme with/without an

extension, preferably, Readme.txt readme files should not contain jargon and overly technical

language and should conform to house style Include these elements in the file,

• Title of the file centered in the text area, with the date• Any necessary copyright notices.• Introductory paragraph explaining the purpose of the file• Optional section titled “How to Use This Document”• Contents listing all the section headings• Procedures • Tables• Errata and Corrections


18

Bibliographies

A bibliography is an alphabetically arranged list of books, articles, or other source material used in the preparation of the document.

You do not need to cite a date of access for CD-ROMs and similar media.

o Examples:

Dupre, Lyn. Bugs in Writing: A Guide to Debugging Your Prose. Reading, MA: Addison- Wesley Publishing Co., 1995.

Vijayan, Jaikumar, and Mindy Blodgett. “Train Wreck at DEC.” Computerworld. July 8,

1996, 1, 15.


19

Titles of Publications• The title page of a printed book includes the product name and the product

descriptor.• Online documentation can use any of the titles listed in MSTP manual

Title Audience Content

Administrator’s Guide

Technical support personnel,system and networkadministrators

Task-oriented informationabout installing, configuring,and managing a product.

Companion End usersOverview of product features.Often highlyvisual and informal.

Installation Guide All usersInformation about how toinstall the product.

MSTP vs. Chicago Manual : Comparison

20

MSTP is a “house -style” of Microsoft Corporation vs. Chicago manual is a generic style guide adopted by American publishing houses

MSTP is more aligned to software products documentation (MS Windows oriented) vs. Chicago manual caters to all types of industries

Chicago manual is an exhaustive volume available in Online and Print vs. MSTP primarily addresses document writers and users of Microsoft products

MSTP and most other organizations’ style guides refer to CMS

References

http://www.futurestate.com/assets/techwriting_guidelines.pdf

21

MSTP-V3_2.pdf

Cisco_stylegd.pdf

http://people.engr.ncsu.edu/txie/publications/writeissues.pdf

http://www.chicagomanualofstyle.org/access/intercept.epl?path=/forum.html

AQ&

THANK YOUTHANK YOU

22

Our purpose is to inform, not to entertain. So our writing must be informational.

Documents

Common Style Problems Speaker: Roshni Kamath Date: 23-Sep-2013 1