Please use the form below to provide your feedback. Because your feedback is valuable to us, the information you submit in this form is recorded in our issue tracking system (JIRA), which is publicly available. You can track the status of your feedback using the ticket number displayed in the dialog once you submit the form.

Style and Voice

    +

    Below is our documentation style guide:

    • Write in the present tense.

      • Yes: the button activates the widget

      • No: the button will activate the widget

    • Write in the second person.

      • Yes: you

      • No: I, we, our, one

    • Use active voice, not passive.

      • Active: The dog ate the bone.

      • Passive: The bone was eaten by the dog

    • Use plain, clear, and concise language.

      • Use “buy” instead of “purchase”, “help” instead of “assist”, “about” instead of “approximately”, and so on.

    • Use simple sentences.

      • For clarity, try to split sentences with more than 25 words.

    • Use short paragraphs.

    • Use contractions, such as can’t and won’t.

    • Write in American English spelling and word usage.

    • Use consistent terminology (this isn’t creative writing, so you don’t need to describe the same thing differently every time you mention it).

    • Spell out acronyms and include them in parentheses the first time they are used in a document, e.g., General Motors (GM). Common acronyms like NoSQL don’t require spelling out.

    • Use parallel structure in lists (that means use the same sentence pattern for each item). If your list is made up of fully formed sentences then they should end with full stops.

    • Use title case for page titles and section headings (capitalize all significant words, use lowercase for words like “to”, “and”, and “for”).

    • Avoid specifying version numbers whenever possible. Instead of Couchbase Server 4.0, just write Couchbase Server.