Heretto Style Guide

Maintaining a style guide promotes consistency and reduces questions about style.

Remember: We develop the Heretto Style Guide with our content needs in mind. We recommend developing your own style guide that aligns with your organization goals.

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.

Table 1. General Terms
PreferredNon-preferredExample
shows, appearsdisplaysThe element appears.
enableallowThe feature enables you to do something.
file namefilenameEnter a file name.
imagepicture, photoSelect an image.
screenshotscreen capture, screen imageUpload a screenshot.
wantwish, desiredSelect the option that you want to enable.

pop-up

popup

The browser blocks pop-ups from automatically showing up on your screen.

Table 2. Windows and Panes
TermUsageExample
windowlarge interface areas that contain buttons, fields, and a close icon.In the Bulk Change window...
dialogsmall interface areas, usually for errors or confirmationsIn the Insert dialog...
panedistinct interface areas grouping related items typically placed on the right or leftIn the Activity pane...
Table 3. Selectable Areas
TermUsageExample
drop-down menuselectable list items in a menuFrom the the More drop-down menu, select...
check boxselectable boxesSelect the Owner check box...
fieldarea where you can enter text stringsIn the Keys field, enter...
Table 4. Actions
TermUsageExample
clickinteractions with buttons, icons, or linksIn the content library, click the Open icon.
right-clickopening a contextual drop-down menuIn the content library, right-click a file and...
selectinteractions with a drop-down menuIn the More drop-down menu, select...
select and clearinteractions with a check boxSelect the check boxes next to the files you want to rename.
entertyping text into with a text areaEnter a title for your file.
navigatefind a file or folderNavigate to the image you want to upload.
placecursor locationPlace 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 name
    Note: 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 Cmd > C .

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...”