Common Style Problems

Download Report

Transcript Common Style Problems

Common Style Problems
Roshni Kamath
• What is a style guide
• Why Style guides are necessary
• Common Style Problems
Measurements and Units of Measure
Names of Special Characters
Telephone Numbers
Time Zones
URLs, Addresses
Company with Product Names
Version Identifiers
Readme Files and Release Notes
Titles of Publications
• MSTP vs. Chicago Manual : Comparison
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.
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
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.
Common Style Problems
 Dates
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
the 1980s and ’90s
23 February 2000
April 21st
- no difference -
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
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
* Use sentence-style capitalization for * In a Warning, the word on or off
UI specific element.
appears in uppercase (ON or OFF)
Common Style Problems
 Measurements and Units of Measure
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
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
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
Common Style Problems
 Protocols
 A protocol is a standard for communication between
 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:
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
(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
Common Style Problems
 Time Zones
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).
The show begins at 19:00 Pacific Time
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
mean time
: eastern standard time
: Pacific daylight time
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
 Each of these main elements is in lowercase type, unless case
is important.
 URLs often appear at the end of a sentence
mailto:[email protected]
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.
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.
The Cisco IOS software provides
many performance benefits.
Common Style Problems
 Version Identifiers
 Product and product component names can include version
information by special identifier
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.
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
Internet Explorer 4.0
Microsoft Exchange Server 4.0.829
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
Errata and Corrections
Common Style Problems
 Bibliographies
 A bibliography is an alphabetically arranged list of books,
articles, or other source material used in the preparation of the
 You do not need to cite a date of access for CD-ROMs and
similar media.
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.
Common Style Problems
 Titles of Publications
The title page of a printed book includes the product name and the product
Online documentation can use any of the titles listed in MSTP manual
Administrator’s Guide
Installation Guide
Technical support
system and network
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.
MSTP vs. Chicago Manual :
 MSTP is a “house -style” of Microsoft Corporation vs. Chicago
manual is a generic style guide adopted by American publishing
 MSTP is more aligned to software products documentation (MS
Windows oriented) vs. Chicago manual caters to all types of
 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
Our purpose is to inform, not to entertain. So our
writing must be informational.