Getting Started on the Community Site: Concise Blog Post Style Guide

Author:

Sheila Albertelli

Created at:

Jul 2021

Updated at:

Sep 2022

General guidelines:

  • Make sure your article has been through a peer and/or tech review to ensure accuracy.

  • Use American English, and a conversational writing style. If you prefer formality, that’s fine, too.

  • Refer to readers and those mentioned in your article as you, the user, and the end user as appropriate.

  • Avoid gender-specific pronouns. Use they/their in place of him/her, and his/hers.

  • Write active sentences using active voice and strong verbs.

    • Ex.: Use the noSession query string parameter to authenticate without a session.

  • Write short, concise steps equivalent to one or two actions.

    • Ex.: Choose Add Users from the Actions menu.

  • Use the same words in the same way with the same meaning.

    • Ex.: if you use close as a verb, do not use close as an adjective. Use a synonym like near.

  • Attribution for claims, facts, and figures:

    • Use objective third-party sources like Gartner, IDC, …

    • Ensure content is current and recent (published in the last 12 or so months).

    • Ensure any written evidence is unbiased.

    • Make any comparisons accurate (apples to apples).

  • Disclose any conflicts of interest at the beginning of your article.

  • Do not plagiarize.

  • Do not libel a person or company.

  • Do not distort or manipulate data.

Capitalization

  • Use initial caps for the title of your article. Ex.: Configuring ForgeRock Identity Cloud as a SAML 2.0 Identity Provider.

  • Use sentence case for headings and subheadings in your article. This means you initial cap the first letter of the first word, and use lowercase for the other words. Ex.: Learn how LDAP works

Formatting

  • UI elements: Formatting is optional. If you feel strongly about it, bold UI elements, including menu selections.

  • Acronyms and abbreviations:

    • Define acronyms the first time they appear in running text, and use them consistently in your articles.

    • For example, if you define single sign-on as SSO at first reference, use SSO and not single sign-on at every subsequent mention.

  • Code blocks and samples:

    • Use the menu bar for preformatted code block style

    • Use MarkDown or HTML for code block style.

  • Commands, file names, and other literals:

    • Use the formatting menu in the composer

    • MarkDown or HTML for both code block and inline code styles:

    • Ex.: the curl command, the .war file

  • File paths:

    • Linux: c:… / (forward slash)

    • macOS: /

    • Unix: /

    • Windows: C: … \

  • New or emphasized terms: No formatting is needed. If you must format, please use use italics instead of quotes.

  • Prompts:

    • Unix: $ am400_status_all.sh

    • Unix root user: # am400_status_all.sh

    • Windows: C:\

  • References to ForgeRock publications and external publications:

  • References to external (non-ForgeRock) publications, such as Medium articles or internet-drafts:

Product names and their acronyms/abbreviations

ForgeRock® + product name + acronym in parentheses:

  • ForgeRock® Access Management (AM)

  • ForgeRock® Directory Services (DS)

  • ForgeRock® Identity Management (IDM)

  • ForgeRock® Identity Gateway (IG)

  • ForgeRock® Identity Platform (Identity Platform, the platform)

  • ForgeRock® Identity Cloud (Identity Cloud) Note: Do not use: FRIC, FRIG, or any FR-ism, or ID Cloud.

  • ForgeRock® Autonomous Identity (AutoID)

  • ForgeRock® Identity Governance and Administration (IGA)

  • ForgeRock® Identity Message Broker (IMB)

  • ForgeRock® Identity Edge Controller (IEC)

  • ForgeRock® Common REST (Common REST). Not to be confused with the Scripted CREST connector, which is IDM’s connector.

Punctuation

  • Apostrophe:

    • Use to indicate possessive. Ex.: the server’s configuration.

    • Do not use to indicate plural.

  • Comma:

    • Use serial or Oxford commas between three or more items in a series.

  • Dash:

    • Use an em dash (—) to emphasize words in a sentence, or to replace parentheses.
      Ex.: Create a schema customization in compact syntax—dbsvg.rnc.

    • Use an en dash (–) to connect numbers such as a page.

    • Do not add a space before and after either type of dash.

  • Hyphen is sometimes confused with a dash. They are not the same.

    • A hyphen joins two words that serve as an adjective before a noun. Ex.: base-level property, easy-to-use.

  • Italics: Use for emphasis.

    • Ex.: This version is a major improvement.

  • Parentheses:

    • Use parentheses to include explanations, acronyms, or to enclose a full parenthetical sentence. Punctuate after parentheses, not before.

    • Ex.: This guide also lists and describes each command-line interface (CLI) administration tool.

  • Periods, aka full stops:

    • Use a period/full stop as end punctuation for all full sentences in a list or table. Sentence fragments do not need end punctuation.

  • Quotation marks:

    • Use to enclose titles:

      • Ex.: Now that you have installed ID with a “Getting Started” configuration, you will learn how IDM reconciles information.

  • Semicolons: Use as a pause between two connected ideas in a series.

    • Ex: A value of true auto-accepts the license; however, any other value is assumed to equal false.

  • Slashes: Use in file paths, known terminology (client/server), in UI elements as they appear in the product, with the and/or construction.

Terminology

  • Use full names for commands, such as the curl command. the .war file, …

  • Log in/Log out: Verbs to use for authent