Basic Rules and Guidelines

Although the concept of right or wrong does not apply to help topics, considering the industry best practices always proves invaluable in terms of quality, cost-savings, and user satisfaction.

In This Article

What Is Good Documentation?

  • Easy to use

    • Task-oriented—Focus on helping users to achieve their goals.
    • Accurate—Deliver documentation that is free from mistakes and errors.
    • Complete—Include all needed parts and those parts only.

  • Easy to understand

    • Clear—Say what you have to say in a simple and clear way.
    • Concrete—Focus on the issue and stay on topic.
    • Consistent—Adhere to writing conventions.

  • Easy to find

    • Well-structured and organized—Ensure the coherent arrangement of information.
    • Retrievable—Make the information easy to find.
    • Visually effective—Apply attractive layouts, illustrations, icons, color, typefaces, fonts, point size, line length.

Steps to Good Documentation

Apply a structured and focused approach towards creating new documentation.

  1. Determine the purpose and the use of the documentation.
  2. Identify the target audience.
  3. Interview the Subject Matter Experts (SMEs) and gather the information you need.
  4. Plan the content.
  5. Create the document.
  6. Build an output locally and verify the content and the presentation.
  7. Provide the output to SMEs for review.
  8. Solicit peer review.
  9. Publish.

On General Structure

  • Keep articles short so that users do not have to scroll many times until they reach the end.
  • Keep articles visually well-organized and logically structured. As a rule of thumb, the attention span of users nowadays is less than seven seconds.

  • Start each article with a short introduction that isn't longer than a couple of sentences. Use the introduction to:

    • Provide a short overview of the component, feature, or thing that you cover in the article.
    • Explain what you describe in the article and provide context.
    • Explain the business need, problem, or situation that the article subject solves.

  • For better readability and orientation, introduce each new topic or aspect within the article with a sub-heading.

  • For better customer experience, introduce individual features in individual articles—this improves SEO and lets you introduce features in more detail.

  • For better navigation and indexation, try to include a See Also, Suggested Links, Next Steps, or similar section at the end of each article.

    Use the Next Steps section in tutorials and articles about features that span multiple articles and to link features that are commonly used together.

The Essentials

To ensure quality for the Progress end-user documentation, follow the general guidelines and adopted best practices at the company.

In This Section

Write in American English

Guidelines

Code follows the en-US spelling rules so it is logical to use American English for the content we produce too.

American English British English
behavior behaviour
color colour
organize organise
license licence
center centre
canceled cancelled

Use the Active Voice

Grammar Pool

  • The Active Voice indicates that the subject of the sentence performs the action, which is expressed with the verb. The Active Voice is more concise and stronger than the Passive Voice and indicates the agent (doer) of the action.

    An example of the Active Voice is "Progress released their Kendo UI for jQuery library a couple of years ago."

  • The Passive Voice indicates that someone or something acts upon the subject.

    An example of the Passive Voice is "The Kendo UI for jQuery library was released a couple of years ago (by Progress)."

  • In technical documentation, Passive Voice sounds sloppy and is unclear and unengaging for the user. Even if you indicate who is performing the action (for example, "The response is sent by the server."), the result is still not as convincing as if you construct the sentence in the Active Voice (for example, "The server sends the response.").

Guidelines

  • Avoid using the Passive Voice as in "was sent", "is created", and so on, whenever possible.
  • Yet, if you opt for the Passive Voice, use it consistently within a sentence.
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

Grammar Pool

  • The Imperative Mood expresses demands, instructions, or requests.

    For example, "Click the Save button.", "Return to the Inspectors tab.", and so on.

  • Usually, speakers use the second person "you" (plural or singular) with an unspoken "you" for the subject ("Follow the instructions", "Select the option", and so on).

  • It may bother you to "give orders" but cognitive science has it: this is the best way to hammer home instructions and the easiest way for the user to quickly grasp what needs to be done.

Guidelines

  • Use the Imperative Mood.
  • Do not use "please note" or similar phrases, which do not add up to the content and are too generic to bring any useful information. Generally, avoid "please" as it also goes against the adopted tone and voice best practices.
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.
For more information on how to configure your ASP.NET application, please visit http://go.microsoft.com/fwlink/?LinkId=169433. For more information on how to configure your ASP.NET application, visit http://go.microsoft.com/fwlink/?LinkId=169433.

Avoid Gerunds and -ing Forms in Text

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

Grammar Pool

  • The Gerund is a verb in its "-ing" form that functions as a noun to name an activity rather than a person or thing.

    For example, "creating" as in the act of creating ("Creating objects with your hands helps overcome depression."), "writing" as in the act of writing ("Writing documentation is thrilling."), and so on.

  • Any action verb can be made into a Gerund.

  • "-ing" forms are ambiguous and can be easily confused because in English a word ending in "-ing" might be used as:

    • A verb in a continuous tense, for example, "She is running weekly now."
    • An adjective that refers to a noun, for example, "They met the running woman that morning."
    • A present participle of a verb that functions as a noun, for example, "Running is bad for your joints."
    • An adverbial participle, for example, "Running, they reached the bus station."

Guidelines

  • Minimize the use of gerund and "-ing" forms in text.

    Not that good Much better
    Advocate requesting assistance. Request assistance.
    Indicate the field of the data item that is used when searching for suggestions. Indicate the field of the data item that is used when the user searches for suggestions.

  • Revise "–ing" adjectives which follow and modify nouns.

    Not that good Much better
    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.

  • Eliminate or rewrite dangling and unnecessary "-ing" phrases.

    Not that good Much better
    When using a Wi-Fi hot spot, the file sharing of your laptop does not need to be enabled. When you use a Wi-Fi hot spot, the file sharing of your laptop does not need to be enabled.
    Enter 14 as the third split point, making sure you select Add Branch. Enter 14 as the third split point. Be sure to select Add Branch.
    Using AppleTalk access lists simplifies network management. AppleTalk access lists simplify network management.

Use Simple Tenses

Grammar Pool

  • Present tenses are direct and active.

    For example, Present Simple as in "The component uses the Angular Service to create Dialog instances dynamically."

  • Present tenses help readers to quickly scan the material.

Guidelines

  • Try to use the Present Simple Tense as much as possible.
  • Prefer the Present Simple to 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.
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 Short Sentences and Paragraphs

Guidelines

  • Keep sentences and paragraphs short and concise. Short paragraphs also add whitespace to the documentation and make it easy to absorb.
  • Split complex sentences in two or more shorter sentences.
  • If a sentence or a paragraph is becoming too long, consider splitting it.

  • As a rule of thumb:

    • Keep the length of a sentence up to 25 words.
    • Use between two and four sentences in a single paragraph.
    • Keep the length of a paragraph up to six lines.
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

Grammar Pool

  • Users struggle over the implied meaning of "should"—whether what should be done is necessary, obligatory, or recommendable.
  • While "should" transmits indecision and lack of commitment, "have to" sounds realistic, direct, and action-oriented.

  • "Should" is ambiguous because it can imply any of the following:

    Possible Implied Meaning Avoid Reason for Avoidance Use Instead
    Something is expected and likely to happen. The Kendo UI Grid component should render a button. This example implies that we are not sure that the Grid is expected to render a button.
    However, if it is us who created the Grid, it is much of a problem if we are not sure of the expected Grid behavior.    		 To avoid such uncertainties, rephrase to The Kendo UI Grid will render a button.
    Something is recommended. You should enter the key. It is not clear if the component will still work if the user does not enter the key (is "should" used as a recommendation?) or if the component will not work at all (are we kindly asking the user to submit the key for the component to work?). To avoid such misinterpretation, directly address the user with Enter the key. or You have to enter the key., or add any additional information to explain that entering the key is not mandatory but will add up to the performance, for example.
    Something is asked in a polite way. You should enter the key. Technical documentation is not the right place for politeness. Technical documentation provides users with information that is not subject to interpretation but is clear and instructive. Again, refer to the 2nd example.

Guidelines

  • Use "have to" or "has to", "need to" or "must" to express obligation.
  • Avoid using "should". Instead of "could" and "would", use "can" and "will".
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.
If you run that code, the ListView would render its first item as active. If you run that code, the ListView will render its first item as active.
To enable editing, you could set the built-in editable option of the Scheduler to true. To enable editing, set the built-in editable option of the Scheduler to true. (In this case, it's better to skip the "can" modal verb and use the Imperative Mood to directly address the user.)

Best Practices and Recommendations

To ensure the documentation is logical and clear, follow the adopted guidelines that are based on the industry best practices.

In This Section

Logic and Precision

Guidelines

  • Pay attention to the literal meaning of each sentence.

    The following table provides an example on restructuring texts for making them easier to grasp.

    Not that good Much better
    This report compares the salaries of different departments for employees who have the same education level. This report compares the salaries of employees who have the same education level, grouped by department.

  • Use nouns as nouns and verbs as verbs.

    The following table provides an example on restructuring texts for avoiding ambiguity.

    Not that good Much better
    To action this report, you must respond by selecting either Resend to Approver or Resend to Approver’s Manager. To resubmit the report for approval, select either Resend to Approver or Resend to Approver’s Manager.

  • Do not add verb suffixes or prefixes to nouns, acronyms, or conjunctions.

    The following table provides an example on avoiding making up technical terms that might be unknown to your users.

    Not that good Much better
    If a variable is VDEFINEd more than once in any step, then the next reference to that variable will cause a storage overlay. If a variable is defined by more than one VDEFINE statement in any step, then the next reference to that variable will cause a storage overlay.

Verbs and Actions

Guidelines

  • Use an action-centered writing style through:

    Not that good Much better
    VMDOFF specifies whether metadata verification checking is to be performed on the data model. VMDOFF specifies whether to verify the metadata of the data model.

  • Use simple verb phrases.

    Not that good Much better
    Before taking this course, you are supposed to have completed XX101. Before taking this course, complete XX101.

  • Keep phrasal verbs together.

    Not that good Much better
    Turn the zoom tool off by clicking the circle tool. Turn off the zoom buy clicking the circle tool.

Noun Phrases

Grammar Pool

Noun phrases include a noun (person, place, thing) and the modifiers which define it. For example, "that clever limping dog", "Aunt Miriam's crazy little dog", "the miserable dirty little cat on the sofa", and so on.

Guidelines

  • Stick to short noun phrases as the long ones embarrass the comprehension and might lead to ambiguity.
  • Revise the length of the noun phrases. As a rule of thumb, avoid using noun phrases longer than two words.

You can apply any of the following revision strategies:

  • Eliminate unnecessary words (reduction).
  • Show relationship between nouns (hyphenation).
  • Place one or more words either in a prepositional phrase or in a relative clause (rearrangement).
Not that good Much better
The STYLE option specifies the style element to use for classification variable name headings. The STYLE option specifies the style element to use when names of classification variables are used as headings.
The default column pointer location is column one. The default location of the column pointer is column one.
Andrew plans to keep all the plantings, including fragrant spearmint and ginkgo biloba trees. Andrew plans to keep all the plantings, including the fragrant spearmint and the ginkgo biloba trees.

Prepositional Phrases

Grammar Pool

Commonly, prepositional phrases start with a preposition and end with the "object" of the preposition, for example, "on the table", "over the rainbow", "with a beautiful woman", and so on.

Guidelines

  • Clarify what each prepositional phrase is modifying or referring to by placing it in the right location.
  • If the prepositional phrase modifies a verb phrase, change its location.
  • Learn More: Prepositions in Common Phrases
Not that good Much better
Only 17 characters are available for the table name on a standard tape label. On a standard tape label, only 17 characters are available for the table name.
Run the following command and pass the connect method before you log the issue. Before you log the issue, run the following command and pass the connect method.
It will rain cats and dogs according to the forecast. According to the forecast, it will rain cats and dogs.

Pronouns

Grammar Pool

Generally, pronouns replace nouns. For example, "I", "you", or "her" stand for me as a technical writer, you as a user, her as in referring to a woman, and so on.

Guidelines

  • Make sure readers are able to identify to what each pronoun refers. Third person singular and plural pronouns, when used as subjects ("it", "they"), objects ("it", "them"), or possessives ("its", "their") are problematic because they sometimes may refer to more than one person or object.

    Not that good Much better
    Once you define the basic structure of your table enhancing it is easy. (Do we refer to enhancing the table or its structure?) Once you define the basic structure of your table, enhancing the table is easy.

  • Avoid writing in first-person plural ("we", "our") because it makes the document less objective and the reader is not able to identify who hides behind the pronoun—the company, the developers, or the document author.

    Not that good Much better
    To help with this task, we exposed the CancellationToken parameter. To help with this task, the component exposes the CancellationToken parameter.
    In this example, we have a spreadsheet with a width that is larger than its height. In this example, the width of the spreadsheet is larger than its height.

  • Do not use "this", "that", "these", and "those" as pronouns.

    Not that good Much better
    Apply all the manual adjustments. These are listed on the Rules tab of the Adjustments window. Apply all the manual adjustments that are listed on the Rules tab of the Adjustment window.

  • Be careful with the use of personal pronouns and the unnecessary gendering of the language.

  • Learn More: Personal Pronouns and Gender Neutrality

Modifiers

Grammar Pool

Modifiers are words, phrases, or clauses, which function as adjectives or adverbs to describe a word or make its meaning more specific:

  • When a modifier is an adjective, it modifies a noun or a pronoun.

    For example, "If I were you, I'd purchase an annual subscription."

  • When a modifier is an adverb, it modifies a verb, an adjective, or another adverb.

    For example, "The team are playing fabulously today."

  • When modifiers are phrases or clauses, they play the role of adjectives and adverbs.

    For example, "The kid with the red ball is Emily's son."

Guidelines

  • Place "only" and "not" as close as possible to whatever they are modifying.

    The following table provides examples on how positioning the "only" modifier in different places changes the meaning of the sentence.

    Change of position Corresponding change of meaning
    Only I hit him in the eye yesterday. No one else did any hitting.
    I hit only him in the eye yesterday. I didn’t hit anyone else.
    I only hit him in the eye yesterday. I didn’t shoot him in the eye.
    I hit him only in the eye yesterday. I didn’t touch any other part of him.
    I hit him in the only eye yesterday. He had just one eye.
    I hit him in the eye only yesterday. Not long ago, recently.
    I hit him in the eye yesterday only. Not any day other than yesterday.

  • Hyphenate "-ing" adjectives and nouns in compound modifiers.

    Not that good Much better
    The platform suite includes a Scheduler and a load sharing facility. The platform suite includes a Scheduler and a load-sharing facility.
In this article
Related articles
Not finding the help you need?