Professional Documents
Culture Documents
Style Guide
Style Guide
Spring 2020
1
Numbers and Ranges 22
Trademarks 22
FREQUENTLY MISUSED / MISSPELLED WORDS 23
INTRODUCTION
The following section provides us with details on what a style guide is, exactly, why it’s important, and
what the purpose is for creating one for our class.
This guide provides "best practices" instructions for our technical documentation writing and editing
standards.
INFORMATION ARCHITECTURE
2
▪ Organization that matches the inherent structure of the content helps a user recognize patterns
to make sense of the information. These include chronological, spatial, comparison-contrast,
cause-effect, and topical patterns.
▪ Grouping related ideas helps readers comprehend.
▪ Documents may also be structured for reuse or may be structured according to organizational
templates.
o Note: DITA is particularly helpful for documentation reuse.
Consider the most important components when writing or creating technical documentation:
● Who is the audience?
● What is the purpose of the document?
3
Applying Minimalism: Choose an Action-Oriented Approach
Avoid marketing “marcom”-speak (which emphasizes benefits over features)
● They have the product - they don’t need to be sold on it
Eliminate distracting, cumbersome introductory material:
● About this book, guide, document, etc.
Emphasize tasks over concepts
● Users avoid long conceptual information
○ Embed necessary small concepts at the beginning of tasks to provide context
○ Refer to larger concepts elsewhere in the documentation
○ Eliminate concepts that are not essential to the task or goal
For example:
1. DISPLAY WINDOW. Custom English 1. Enter your user code. With Minimalism
Display Touchpads: 2-line, 32-character applied, the
Liquid Crystal Display (LCD) touchpads function is action-
that display protection point oriented and includes
identification, system status, and only the necessary
messages. English Display Touchpads: information.
Display protection zone ID and system
status messages using pre-designated
words in the LCD display.
4
● Link tasks to the user’s workflow
● Provide a clear starting point for all process flows
● Keep procedures short and focused
● Use headings that reflect the user’s goals
● Assume the reader is qualified to perform a task
5
INSTEAD OF (passive
USE (active voice) EXAMPLES NOTES/EXCEPTIONS
voice)
6
USE INSTEAD OF EXAMPLES NOTES/EXCEPTIONS
7
USE INSTEAD OF EXAMPLES NOTES/EXCEPTIONS
Past: “I attended
Past Tense school.”
Present Tense
Future Tense Future: “I will attend
“I attend school.”
school.”
8
USE INSTEAD OF EXAMPLES NOTES/EXCEPTIONS
9
Unbox all components
before you set up the
lighting system.
Set up: build, design,
Use set up when an make, create The setup time for the
action is taking place. smart light bulb
Setup: compose,
installation is five
Use setup when not arrange, prepare
minutes.
referring to an action. Log in: sign in, sign on,
After opening the smart
Use log in when an log into, log on, connect
light bulb app, log in.
action is taking place. Login: credentials,
If you need to reset
Use login when not username and
your login for the smart
referring to an action. password (if used
light bulb app, find the
together), portal
‘reset password’ button
at the bottom of the
login page.
Use Bold Text for Names of Fields, Buttons, etc., Indicating Action on the User’s Part
10
Bold the names of panes, screens, tabs, windows pages - as well as the names of buttons, etc. - so that
they stand out from regular/body text, and indicate orientation/action for the user.
Click Save As
Save As “Save As”
Choose Undo from the
Undo Undo
Edit tab
11
An illustration referred
to in the body text is
inserted on the same
page as referenced with
a labeled caption. If an illustration is
Illustrations referenced in a text, it
Graphics MUST appear on the
Ex. “As shown in Figure
Captions & Page same page with an
1.2 below…”
References accompanying
Caption Ex. label/caption.
Figure 1.2 The
illustration depicts how
solar energy is
converted.
12
WRITING INSTRUCTIONS (Task-Based Authoring)
A task topic documents the result a user wants to achieve, instead of the product/feature they are
using.
Product capabilities should be presented in context of the task they support so that users can
understand how the capabilities relate to their performance.
For example: If there is a Properties function in your product, instead of creating a task topic for
“Specify Properties,” create a task topic for a specific property, “Determine Your Hard Drive
Space,” because this is an actual task that a user must perform.
13
General guidelines for concepts
A concept topic is intended to capture content that tells you “what something is” or "how something
works." The information is typically presented as paragraphs that describe the background and context
of a single subject. Use a concept topic to describe the core knowledge that someone needs to
understand how a product works or how pieces relate.
Keep the following guidelines in mind when authoring concept topics:
● Describe one concept per topic
Tip: The advantage of separating your concepts is that users can find and read only what they
need, and we can more easily reuse those concept topics elsewhere in our documentation.
● Create a concept topic only if the idea can't be covered more concisely elsewhere
Tip: Create a concept topic to cover an idea that requires something more than a glossary
definition or a passing mention in a task topic.
● Separate task information from conceptual information
Tip: Write conceptual information as concept topics; task-oriented information as task topics.
By adopting input-neutral terms, users can universally follow any given set of our instructions,
regardless of how they are accessing the help or what device they are using (e.g., they might be on a
mobile device where “swipe” and “tap” come into play).
Tip: Minimize directional terms (left, right, up, down) as the only clue to location. This is problematic
14
because UI arrangement changes relatively frequently; orientation is different on mobile; etc. Instead:
focus on giving direction based on the UI's components, instead of where something is located.
UI Text
● Fastpath- Use to direct the user to their desired destination by calling out each breadcrumb on a
sitemap. It’s useful when the path through navigation is long or complicated somehow.
○ To add a lightbulb to your cart, go to Store > Lightbulb > Actions > Add.
Choose
Selections on a desktop
Click Click the submit button. Instead, use verbs that
Selections made with a make sense on multiple
15
mouse platforms, like select
16
or italic
17
Avoid this if possible. If
you do use it, make
Interactions with a Right-click to display sure you are describing
Right-click
mouse the options. a computer-based task
and not one for a touch
device.
● Text
● Links
● Objects Select the Print icon.
● Cells Select Ctrl+Alt+Delete. The selected item/text
Select
● Check boxes Select the check box to is called a “selection.”
● Buttons agree to the terms.
● Icons
● Images
(Enlarging?)Viewing a
document (screen?) (Locate the magnifying
Zoom, zoom in, zoom
closer or further away glass icon?)
out
(decreasing?) on the Press Ctl and +
screen
Mobile-Specific UI Navigation
[note: “Select” might be a good universal word instead of “click” (web) and “tap” (mobile)]
18
● Disable Tap the “enable”
button to receive
notifications.
19
acronym in the title and light bulbs.
then introduce the
acronym in parentheses
in the paragraph text. Unfamiliar: Light Bulb
Surplus Ordering
Plurals
Possessive
Only use the possessive The ALA’s designers
form for acronyms that created a marvelous
refer to individuals and display.
organizations.
Capitalization Acronyms
20
Products, features,
company names,
proper nouns, etc.
Titles
Note
21
Use Important to
convey information that
Important: Make sure
is necessary to begin a
the base numbers on
task. Failure to heed
Important the bulb and socket
this information will
match before
halt the user’s progress
proceeding.
but will not cause injury
or harm.
22
FREQUENTLY MISUSED / MISSPELLED WORDS
Here’s a list of frequently misused/misspelled words for easy reference.
23
Affect is a verb that
means “impact or
“You can affect change
change”.
affect, effect by voting”
Effect is a noun that
“Side effects include”
means “the result of a
change”.
Assure refers to
instilling confidence or
He was assured, by his
dispelling doubt.
doctor, that he was in
Insure is an agreement
good health.
that provides
protection from
assure, insure, ensure She needed to insure
financial loss, and is
her car with car
often associated with
insurance.
insurance.
I ensured no one would
Ensure refers to making
hear the phone call.
sure something will
occur.
Complement refers to
The new light bulb
something that
complemented the
completes something
lighting of the house.
complement, else.
I complimented the
compliment Compliment refers to a
company on the great
courtesy in the form of
quality of their light
admiration, esteem,
bulbs.
approval.
“The motion-sensored
light turns on
Continually refers to
continually throughout
intermittent action.
continually, the day.”
continuously “If left on continuously,
Continuously refers to
the light bulb will burn
uninterrupted action.
out.”
24
The camera was
discreetly hidden inside
the ordinary-looking
Discreet means to be
light bulb.
private or unobtrusive.
discreet, discrete Halogen, incandescent,
Discrete means
and compact-
separate and distinct.
flourescent are three
discrete types of light
bulbs.
Repeated absences
Imply means to suggest imply a lack of student
indirectly, to hint at engagement.
imply, infer Infer means to deduce She could infer from
or draw conclusion the repeated absences
from that there was a lack of
student engagement.
personal, personnel
25
As a contraction,
Your is the possessive
“You’re” is considered
form of the word “you”.
“Your hair is messy.” informal. In formal
your, you’re You’re is a contraction
“You’re a hairy mess!” documents, it’s better
of the words “you” and
to use the full phrase
“are”.
“you are”.
26