Cheat Sheet

This cheat sheet is a user-friendly, quick-reference version of the complete, full Style Guide version at Progress.

The guidelines and recommendations refer to the official product documentations of the company such as KendoReact, Fiddler Jam, and so on.

For general guidance on writing and structuring your articles, refer to the article on basic rules and guidelines:

The rest of this article focuses on the guidelines related to language, grammar, formatting, and so on.

In This Article

Tone and Voice

In this section:

Basic Things to Avoid

  • Do not denigrate or insult any group of people.
  • Do not use jokes at the expense of the users.
  • Do not use "simply", "It's that simple", or "It's easy".
  • Do not use "let's do something".
  • Do not use "please note" and "at this time".
  • Do not use third-person singular pronouns ("he" or "she"). Use "they" instead to avoid gender issues.
  • Do not write in first-person plural ("we", "our").
  • Do not use metaphors or abbreviations.
  • Learn More: Using the Right Tone and Voice

Writing for Global Audiences

Many users are non-native English speakers and come from various cultures. The content we write and the language we use has to translate well and to provide no room for interpretation.

  • Use simple, objective, and non-ambiguous language.
  • Do not use culture-specific language or pop-culture references.
  • Do not be too cutesy.
  • Keep sentences and paragraphs short and concise. If a sentence or a paragraph is becoming too long, split it.
  • Learn More: Using the Right Tone and Voice

Common Best Practices and Recommendations

Learn More: List of Common Best Practices and Recommendations

General Guidelines for Writing

In this section:

Write in American English

Learn More: Examples of British and American English

American British
behavior behaviour
color colour
organize organise
license licence

Use the Active Voice

Not that good Much better
To access the results that are returned by the query, use standard JDBC syntax. To access the results that the query returns, use standard JDBC syntax.

Directly Address the User

Not that good Much better
After reading this tutorial, the roadmap should be created. After reading this tutorial, create the roadmap.
If you want to enable the filtering functionality of the Grid, you can set the filterable option to true. To enable the filtering functionality of the Grid, set the filterable option to true.

Deliver Gender Neutrality

  • Use "they"/"their"/"theirs" instead of "he"/"him"/"his" or "she"/"her"/"hers", or "he or she"/"him or her"/"his or hers".
  • If impossible to use "their", rephrase the sentence and eliminate the use of the pronoun.
  • Avoid the unnecessary gendering of the language.
  • Learn More: Writing Documentation in a Gender Neutral Way
Not that good Much better
Provide the email of the person that you want to invite and select his IdP. Provide the email of the person that you want to invite and select their IdP.
Equipment installation and setup takes around 16 man-hours to complete. Equipment installation takes around 16 person-hours to complete.

Avoid Gerunds and -ing Forms in Text

For more information on using -ing forms in titles and headings, refer to the section on titles, headings, and subheadings.

Not that good Much better
Advocate requesting assistance. Request assistance.
Indicates the field of the data item that is used when searching for suggestions. Indicates the field of the data item that is used when the user searches for suggestions.
Move the certificate authority to a new server running on a domain controller. Move the certificate authority to a new server that is running on a domain controller.
When using a Wi-Fi hot spot, your laptop's file sharing does not need to be enabled. When you use a Wi-Fi hot spot, your laptop's file sharing does not need to be enabled.

Use Simple Tenses

  • Try to use the Present Simple as much as possible.
  • Prefer the Present Simple to the future tenses.
  • Use future, past, and perfect tenses only when it is confusing to use the present tenses.
  • If you need to talk about past events, use the Past Simple instead of perfect tenses.
  • Learn More: Using an Action-Centered Approach in the Documentation
Not that good Much better
The headerTemplate option specifies the static HTML content, which would be rendered as the popup element header. The headerTemplate option specifies the static HTML content which is rendered as the popup element header.

Use Simple Language

  • Use common en-US vocabulary.
  • Use very specific words and phrases.
  • Avoid using words of foreign origin including Latin abbreviations such as "e.g.," and "i.e.,".
  • Avoid creating new terms.
  • Avoid generalization.
  • Do not use qualifications such as "good", "best", "worst", and so on.
  • Do not use slang, jargon, humor, sarcasm, colloquialisms, idioms, emoticons, and metaphors.
  • Avoid culture-specific references that might not be widely understood, such as holidays and celebrations, monetary units, and phone number and address formats.
  • Avoid using symbols instead of words in running text even if you are space-constrained.
  • Use simpler and shorter words and phrases.
  • Avoid using generic phrases like "there is" and "there are". Such phrases serve a grammatical function but have no real meaning.
  • Learn More: Using Simple Language
  • Learn More: Using Unambiguous Language

Use Short Sentences and Paragraphs

  • Split complex sentences in two or more shorter sentences.
  • As a rule of thumb:
    • Keep the length of a sentence up to 25 characters.
    • Use between two and four sentences in a single paragraph.
    • Keep the length of a paragraph up to six lines.
  • Learn More: Using Short sentences and Paragraphs
Not that good Much better
The PanelBar displays hierarchical data as a multi-level, expandable component and is stateless, which means that to store its state and configuration options, you must use a high-order component. The PanelBar displays hierarchical data as a multi-level, expandable component. To store its state and configuration options, use a high-order component.

Use Properly Should, Could, Must, Have to, Need to

Not that good Much better
The + in the second definition indicates that you should add one or more arguments. The + in the second definition indicates that you have to add one or more arguments.

Commonly Used Words

Learn More: Commonly Used Terms, Words, and Expressions across the Documentation

General Guidelines for Formatting

Elements Formatting Example
UI elements such as buttons or dialog boxes Bold font To submit the form, click Save.
Code such as HTML tags, methods, events, variables, or class names. Code formatting To trigger the save event, click Save.
Keyboard keys Code formatting To save the form, press Ctrl+S.

Company and Product Brand Names

Titles and Headings

In this section:

Consistency

  • The rendered title of the article corresponds to the level-one heading (h1 in HTML or #in Markdown).
  • Keep the title meta element identical to the level-one heading.
  • (Exceptions) For SEO purposes, you can have the meta_title (page_title in earlier versions) (without the product name) differ from the heading (h1 or #) and title.
  • Learn More: Implementing Titles and Headers in the Documentation

Levels

  • The title of the article corresponds to heading level one (<h1> in HTML, # in Markdown). You need to have a single instance of <h1> (#) within the same article.
  • Depending on the product documentation, some Progress sites render headings up to level three (h3 or ###).
  • (Exceptions) The documentation supports all heading levels, so you can still use all through h6 or ######.
  • Learn More: Implementing Titles and Headers in the Documentation

Capitalization

  • Always capitalize:
    • The first and last words within a heading
    • Nouns ("Widget")
    • Verbs ("Render", "Is")
    • Adjectives ("Interactive", "Comprehensive")
    • Adverbs ("Quickly", "Possibly")
    • Pronouns ("It", "Its")
    • Subordinating conjunctions ("If", "Because", "That")
    • All words in phrasal verbs ("Take Off", "Look After", "Turn Up")
    • Prepositions used as element names in the user interface ("The On Button")
    • The first and last word in a hyphenated expression ("How-To Guide", "Out-of-the-Box")
  • Never capitalize:
    • Coordinating conjunctions ("and", "but", "or")
    • Articles ("a", "an", "the")
    • Prepositions unless used as element names in the user interface ("at", "on", "between")
    • "To" when it is part of an infinitive ("Widgets to Beautify Your Mobile Applications")
  • Learn More: Implementing Titles and Headings in the Documentation
Not that good Much better
Adding the about Pull-Down Menu Adding the About Pull-Down Menu
Running the In-browser Client Running the In-Browser Client
Setting up Clicks and Routing Setting Up Clicks and Routing
during Initialization During Initialization
the Template Delegate The Template Delegate
Possible To Port Possible to Port

-ing Forms in Titles and Headings

For more information on using -ing forms (and gerunds) in text, refer to the dedicated section.

While to avoid ambiguity it is not advisable to use -ing forms (and Gerunds) in text, -ing forms are usual and helpful in titles and headings especially when the article describes a process or explains how to do something. For example, "Getting Started", "Installing the Plugin", "Managing the Process", "Handing Off Projects to Developers", and so on.

Style

Lists

  • For steps in procedures, use numbered lists.
  • For same-priority items, use bulleted lists.
  • Introduce lists with a starting sentence that ends in a colon (:).

  • Move as much of the repeating bullet content as possible to the introductory sentence.

    Not that good Much better
    In this version:
    • You can debug on iOS devices.
    • You can develop with Apache Cordova 4.0.0.
    • You can distribute minor app updates over the air.
    		 In this version, you can perform the following tasks:
    • Debug on iOS devices.
    • Develop with Apache Cordova 4.0.0.
    • Distribute minor app updates over the air.

  • Start each list item with a capital letter.

  • End each list item with a period if it is a complete sentence. If any list item requires a period, add periods to all list items.
  • Avoid using articles ("a", "an", or "the") in the beginning.
  • Do not create one-item lists.

  • Introduce parallel structures for the list items.

    Not that good Much better
    Apply any of the following approaches:
    • App update.
    • Reinstalling the app.
    • Remove the app completely, clear the cache, and install it again.
    		 Apply any of the following approaches:
    • Update the app.
    • Reinstall the app.
    • Remove the app completely, clear the cache, and install it again.

  • If the list is more than three levels deep, consider restructuring.

  • If you need to include an explanation, place it in a separate paragraph aligned with the text in the list element.
  • Learn More: Documenting Content in Lists

Metadata

  • Implement a meta block in the <head> section of each article.
  • Always include the title, meta_title or page_title, and description meta elements for SEO purposes and content indexing.
  • The slug is also mandatory. It prevents 404 errors when the item relocates within the documentation site.

  • Use the following syntax rules when you implement the meta elements:

      ---
  title: Data Binding
  position: 1
  meta_title: Data Binding | [Name of Component, Suite, or Else as Agreed with SEO]
  description: "Bind the Kendo UI Grid to a local array or a remote data source."
  tags: Grid, data binding, Kendo UI
  slug: data-binding-autocomplete
  previous_url: /data-management/grid/introduction
  ---

  • Learn More: Implementing Metadata in Documentation

Prefixes

  • Examples of prefixes:
    • Anti-
    • Counter-
    • De-
    • Non-
    • Pre-
    • Re-
    • Semi-
    • Ultra-
    • Un-
  • Always check if the prefixed word exists in a hyphenated or non-hyphenated form on Merriam-Webster.
  • Do not hyphenate the prefixed word if it does not have an established spelling.
  • If the prefixed word has an established non-hyphenated spelling, make sure that the form you want to use conveys the meaning you desire to express. If the non-hyphenated usage creates an ambiguous statement, hyphenate it.

  • Learn More: Using Prefixes in the Documentation

    Not that good Much better
    Recreate the environment.
    (Typically, "to recreate" means "to amuse, to entertain".)     		Re-create the environment.
    (Typically, "to re-create" means "to create again from the ground up".)
    If a non-critical issue occurs, ignore it and continue your work. When a noncritical issue occurs, ignore it and continue your work.

Words for User Interaction

  • For desktop devices—"click" ("double-click", "right-click"), "press", "select", and "deselect".
  • For mobile devices—"tap", "double-tap", "swipe", "tap and hold", "spread", "pinch", and "drag". For Apple iOS 3D Touch—use "touch".
  • For mixed-device purposes—"select", "double-tap", or "double-click".
  • Learn More: Terms for User Interaction with Software

Comments in Code Snippets

Contractions

  • In writing, some contracted forms are acceptable, but may be ambiguous for non-native speakers. Therefore, avoid contracting words.
  • When you want to create emphasis, use the uncontracted phrase.

  • Learn More: Using Contracted Forms in the Documentation

    Use Do not use
    aren't
    can't, cannot
    didn't
    don't, doesn't
    haven’t, hasn’t
    hadn't
    I'm
    		 you’ll (I’ll, he’ll, she’ll, it’ll, we’ll, they’ll)
    you’re (he’s, she’s, it’s, we’re, they’re)
    you'd (I’d, she’d, it’d, we’d, they’d)
    you’ve (I’ve, he’s, she’s, we’ve, they’ve)
    what's, what'll, what'd, what're
    where's, where'll, where'd
    when's, when'd, when'll
    how's, how's, how'll
    won't
    wouldn't
    I’ll, I’ve, I’d
    it’s (it has, it was)
    isn't, aren't, wasn't, weren't

Cross-References

Notes

A Note block indicates neutral or positive information that emphasizes or supplements important points of the main text. A note supplies information that may apply only in special cases. Examples are memory limitations, equipment configurations, or details that apply to specific versions of a program.

To create a note, use the note prefix.

Adding a note


A Tip is a type of note that helps users apply the techniques and procedures described in the text to their specific needs. A tip suggests alternative methods that may not be obvious and helps users understand the benefits and capabilities of the product. A tip is not essential to the basic understanding of the text.

To create a tip, use the tip prefix.

Adding a tip


An Important block provides information that is essential to the completion of a task. Users can disregard information in a note and still complete a task, but they are not advised to disregard an important block.

To create an important note, use the caution prefix.

Adding an important note

Prepositions

In this section:

IN

  • (Do something) In a command mode
  • In a dialog box
  • In a pane
  • (Enter something) In a window
  • (Find something) In a class
  • In a code snippet
  • In a container
  • In a file
  • In a filename
  • In a property
  • In a method
  • In an object
  • (View something) In the example
  • Learn More: List of Common Prepositional Phrases

ON

AT

Screenshots

  • Use the default appearance of the product when you take the screenshot. Avoid using 3D effects.
  • Use arrows for pointing to an element in the screenshot.
  • Minimize empty space in the screenshot.
  • Do not use screenshots wider than 1000 px.
  • For labels, use Arial, 16 pt.
  • Learn More: Adding Screenshots to the Documentation

Captions for Figures, Tables, and Code Snippets

  • Introduce each table, figure, screenshot, code snippet, or demo example with a descriptive sentence or with a caption. For example, "The following table lists the configuration options of the TreeList." (descriptive sentence) or "Available Configuration Options of the TreeList" (caption).
  • Place the caption before the element it introduces.
  • Do not use punctuation in captions unless they are full sentences. If a caption is a full sentence, end it with a period.
  • Render a caption in bold.
  • Because of current technical limitations, an automatic generation of numbers for the captions is not supported. Therefore, for easier maintenance, skip that numbering.
Descriptive Sentence Caption
The following example demonstrates the full implementation of the suggested approach. Example with the Full Implementation of the Suggested Approach
The following figure displays the end result from running the code. Screenshot of the End Result from Running the Code

Tables

In this section:

Table Headers

Table Content

  • For the body text, follow the current general guidelines for capitalization, semantic marking, and so on.
  • All column entries have to contain content. If the information does not apply, do not use dashes. Instead, use "N/A", "Not applicable", or "None".
  • Learn More: Using Tables in the Documentation

The following table demonstrates how to apply the guidelines for presenting the content within a table.

Property name Value type Description
Message string A default message that is sent to each platform for which a vendor-specific payload is not provided. Treated differently on every platform (for example, it appears as an alert on iOS). Note that different platforms have different limits on message length.
Filter string A filter expression specifying which devices must receive the push notification. It represents a stringified JSON object.
NotificationDate date The date and time when you want the push notification to be sent.

Knowledge Base Articles

The Knowledge Base articles include how-to and troubleshooting scenarios. Depending on the type, the KB article has to follow a specific structure, include specific content, and follow rules for creating their titles as well as using proper punctuation.

FAQ Articles

In this article
Related articles
Not finding the help you need?