Common Style Problems
Speaker:
Date:
Roshni Kamath
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
 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
4
Common Style Problems
 Procedures
•
•
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.
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, select
the Comments check box.
5
Common Style Problems
 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
Incorrect
23 February 2000
6/11/99
11/6/99
April 21st
- no difference -
6
Common Style Problems
 Capitalization
•
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.
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 * In a Warning, the word on or off
UI specific element.
appears in uppercase (ON or OFF)
7
Common Style Problems
 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)
5 inches or 5 in.
0.5 inch, 0 inches
8 bits
12 points high
six 1/2-inch cables
•
•
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
1 MB, 12 MB
0.5 kg, 1 kg, 5 kg
1 cm, 6.5 cm
1 ms, 200 ms
56 to 64 kbps; 56–64 kbps
8
Common Style Problems
 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 inches
0.75 gram
35mm camera
8 bits
1-byte error value
Chapter 10, row 3, column 4
00: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–1994
pages 95–110
Twenty-five fonts are included
•
•
•
•
9
Common Style Problems
 Protocols
 A protocol is a standard for communication between
computers
 Most protocols are referred to by their abbreviations
o 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
10
Common Style Problems
 Telephone Numbers
Examples from MSTP
Examples from CISCO Style guide
For U.S. telephone numbers, use parentheses, not
a hyphen, to separate the area code from the
seven-digit phone number.
Inside the USA and Canada, Use the format:
Area code (space) group of first three numbers
(hyphen) group of last four numbers
EXAMPLE Cisco Systems, Inc.,
Americas Headquarters, 408 526-4000
(425) 555-0150
Do 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
12
Common Style Problems
 Time Zones
STYLE in MSTP
STYLE in Chicago Style guide
The names of time zones should be treated as proper
nouns. A time zone
is a geographical area.
•
•
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)
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
•
EST
•
PDT
mean time
: eastern standard time
: Pacific daylight time
13
Common Style Problems
 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 sentence
o
Examples:
http://www.microsoft.com/business/
ftp://www.example.com/downloads/myfile.txt
mailto:someone@example.com
http://preview.cisco.com/en/US/docs/general/style/guide/latest/sg.html
14
Common Style Problems
 Company with Product Names
Examples from MSTP
Examples from CISCO Style guide
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:
Trademark is the legal word for a name given to
a product or service
Microsoft Windows XP, Windows
2000, and Windows NT 4.0
Windows NT version 3.1 or later
In technical documentation, do not use any
trademark symbols with the Cisco name.
Examples:
The Cisco IOS software provides
many performance benefits.
15
Common Style Problems
 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:
o
• Major release identifier: X.x.x
• Minor release identifier: x.X.x
• Update identifier: x.x.X
Examples:
Internet Explorer 4.0
Microsoft Exchange Server 4.0.829
16
Common Style Problems
 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
17
Common Style Problems
 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.
18
Common Style Problems
 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
Administrator’s Guide
Companion
Installation Guide
Audience
Content
Technical support
personnel,
system and network
administrators
Task-oriented information
about installing, configuring,
and managing a product.
End users
Overview of product features.
Often highly
visual and informal.
All users
Information about how to
install the product.
19
MSTP vs. Chicago Manual :
Comparison
 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
20
References
MSTP-V3_2.pdf
Cisco_stylegd.pdf
http://www.chicagomanualofstyle.org/access/intercept.epl?path=/forum.html
http://www.futurestate.com/assets/techwriting_guidelines.pdf
http://people.engr.ncsu.edu/txie/publications/writeissues.pdf
21
THANK YOU
Our purpose is to inform, not to entertain. So our
writing must be informational.
22