Heretto Style Guide
Maintaining a style guide promotes consistency and reduces questions about style.
Acronyms
An acronym is the shortened form of a word or phrase.
Guidelines
- If the acronym is specific to an industry or software and a reader may not recognize it, write it out.
- For every topic, write out the full term, followed by the acronym in parentheses. As you continue writing, you can use the abbreviation in place of the full term.
Example
Each document needs a corresponding Document Type Configuration (DTC). The DTC tells Heretto CCMS what documents to associate with the configuration.
Capitalization
Limit capitalization to proper nouns.
Guidelines
- Capitalize names of people, places, organizations, and interfaces.
- Capitalize names the way they were intended to be capitalized, regardless of their location in the sentence. You can start a sentence with a lowercase proper noun.
- Capitalize topic titles, figure titles, table titles, and section titles.
Example
The Dashboard interface enables you to...
Diction
Preferring some terms over the others makes consistent documentation.
Preferred | Non-preferred | Example |
---|---|---|
shows, appears | displays | The element appears. |
enable | allow | The feature enables you to do something. |
file name | filename | Enter a file name. |
image | picture, photo | Select an image. |
screenshot | screen capture, screen image | Upload a screenshot. |
want | wish, desired | Select the option that you want to enable. |
pop-up | popup | The browser blocks pop-ups from automatically showing up on your screen. |
Term | Usage | Example |
---|---|---|
window | large interface areas that contain buttons, fields, and a close icon. | In the Bulk Change window... |
dialog | small interface areas, usually for errors or confirmations | In the Insert dialog... |
pane | distinct interface areas grouping related items typically placed on the right or left | In the Activity pane... |
Term | Usage | Example |
---|---|---|
drop-down menu | selectable list items in a menu | From the the More drop-down menu, select... |
check box | selectable boxes | Select the Owner check box... |
field | area where you can enter text strings | In the Keys field, enter... |
Term | Usage | Example |
---|---|---|
click | interactions with buttons, icons, or links | In the content library, click the Open icon. |
right-click | opening a contextual drop-down menu | In the content library, right-click a file and... |
select | interactions with a drop-down menu | In the More drop-down menu, select... |
select and clear | interactions with a check box | Select the check boxes next to the files you want to rename. |
enter | typing text into with a text area | Enter a title for your file. |
navigate | find a file or folder | Navigate to the image you want to upload. |
place | cursor location | Place your cursor where you want to insert a table. |
File Extensions
File extensions use different style guidelines depending on the specificity of what you are referencing.
Guidelines
- If you refer to a file type, use all uppercase
For example, write “Upload a PDF”.
- If you refer to a specific file, use lowercase for the file extension
For example, write “Include image.png in the folder.”
Keyboard Key Names
Introduce keyboard key names in the correct DITA elements.
Stylistic Guidelines
- Use abbreviated keyboard key forms
- Capitalize the first letter of a keyboard key nameNote: Some publishing scenarios may automatically capitalize entire keyboard key names.
- Prefer Enter over Return
DITA Guidelines
- To write about a single keyboard key, use the shortcut element nested in the UI control element
- To write about keyboard shortcuts, use the he shortcut element nested in the UI control element, and menu cascade element
Examples
Alt
Cmd
To copy the selected text, press
.Numbers
Using specific guidelines for numbers and digits makes scanning for information easier.
Date and Time
- Use a 12-hour time format and include the 12-hour period and timezone. The timezone should be
abbreviated and in all uppercase.
For example, “The meeting is at 1:00 pm EST.”
- Use a lowercase acronym after the numeric time.
For example, “The revisions were made on 01-31-2030.”
- Use a MM-DD-YYYY format for dates or write the date out in full.
For example, “The meeting is on January 31, 2030.”
Digits
- Spell out numbers one through nine
For example: “Select two options.”
- Use numerals for numbers 10+
For example, “Select 12 files in the file listing.”
- Use a comma in numbers of four digits or more
For example, “There are over 5,000 combinations.”
Punctuation
Heretto follows The Chicago Manual of Style, with some notable punctuation style considerations outlined for reference.
Bullets
- Use a bullet list when organizing three or more items into a list makes more sense.
- Capitalize the first letter of each list item.
- Use parallel structure when writing a bullet list. For example, start each list item with a verb.
- Do not add a period to the end of any list item, even if the list items are complete
sentences.
The only exception is when a list item includes more than one sentence. In this situation, you must add an end punctuation to all sentences in the list item and all list items in the bullet list.
Example
The interface enables you to:
- View activity
- Filter events
- Search keywords
Commas
The Oxford comma is the final comma in a series of three or more items. Using the Oxford comma helps to reduce ambiguity in writing.
- In a series of three or more items, use a comma before “and” and “or”
- Use a comma to connect two independent but connected clauses into a single sentence
- Do not use a comma to connect two independent thoughts
Example
To reduce the ambiguity and make it clear that the dedication is to the writer's parents, to Leroy, and to Joanne, we use the Oxford comma:
"I dedicate this book to my parents, Leroy, and Joanne."
In the following example, we don't know if the book is dedicated to the writer's parents, Leroy and Joanne, or to the writer's parents, as well as Leroy and Joanne.
"I dedicate this book to my parents, Leroy and Joanne."
Periods
- Always use a period at the end of a complete sentence. The only exception to this rule is bullet lists.
- Place periods inside quotation marks at the end of a sentence, unless the parenthetical content is nested in another sentence. In that case, the period should go outside of the quotation marks.
Voice
We want our content to be simple, objective, and professional. However, we also want to maintain a conversational and engaging tone.
Guidelines
- Use active voice
For example, write “We recommend that you do not edit the underlying code.” instead of “It is recommended that you do not to edit the underlying code.”
- Write in the second person narration
For example, write “You can use the History tab to restore a file to the previous state.”
- Keep it simple and direct. Be conservative in adjective and adverb usage, and use simple, common
words.
For example, write “Now...” instead of “Once you have done that...”