Skip to content

Latest commit

 

History

History
204 lines (152 loc) · 11.7 KB

styleguide.md

File metadata and controls

204 lines (152 loc) · 11.7 KB
Raw

Style guide

Follow this style guide to keep our documentation coherent and provide a consistent reading experience to our users. It is loosely based on Google's style guide and partly enforced by Vale.

Minimalism

Users don't read documentation but skim it, so:

  1. Go straight to the point and only provide what is necessary.
  2. Keep your sentences short.
  3. Use bullet lists (a lot).

Only documentation on concepts should be detailed, such as architecture overviews. Task (how to do...) and reference (raw information) topics should be as direct as possible.

Important: Straight to the point doesn't mean incomplete.

English

Think about your international readers and keep your English simple and rather formal:

  1. Use the American spelling.
  2. Write in simple English, but not stupid either: Do not write long sentences, do not use jargon, or use the user's jargon if you must.
  3. Repeating a noun or a subject is ok. Repetition prevents misunderstandings.
  4. Do not use weasel words (often, probably, possibly...).
  5. Do not use adjectives to describe tasks (great, easy/easily, hard...). Technical writing does not judge complexity.
  6. Use phrasal verbs with care (take off, take on, put up, put down...), they are often confusing to international readers.
  7. Avoid using need. It's ambiguous.
  8. Avoid useing must. Just use the imperative and save 2 words (You must create... -> Create).
  9. Avoid generic sentences that can be used for everything such as: This section describes how to... If a sentence can be used for everything, it's useless.
  10. Do not use parenthesis. If something is so unimportant to be in parenthesis, it can probably be deleted.
  11. Do not use Latin abbreviations such as i.e or e.g. i.e, let's use English instead: for example.
  12. Do not describe UI elements or their location in the UI.
  13. Use parallelism correctly (add to/subtract from, import into/export from, etc.).
  14. Use a comma before the conjunction (and, or) that marks the final item in a list of three or more items.
  15. Use prepositions consistently, for example:
    • on the page or on the Features page
    • on the left-side menu or on the leftmost menu
Category Do Don't
Simple English Use the Test API. Utilize the Test API.
Simple English Import the item when the icon is green. The icon has turned green therefore meaning you can now import the item.
Simple English Import the catalog when the icon is green. You need to import the catalog when the icon is green.
Phrasal verbs The window appears. The window pops up.
Weasel word Use this endpoint to implement... This endpoint is often useful when implementing...
Judging complexity To create ABC, click... To create ABC, simply click...
Latin Set a value, for example 32. You can set a value, e.g. 32 .
UI description Click Save. Click the Save button.
UI description Select a value from Suggestion. Use the drop-down list called Suggestion to select a value.
Parallelism Add points to or subtract them from... Add or subtract points from...
Punctuation The card can be active, inactive, or blocked. The card can be active, inactive or blocked.

Active voice

Use the active voice as much as possible. It reads better and sounds more natural in most cases. To force yourself to write in active voice, use you as the subject of your sentence.

You can use the passive form for actions performed by the system.

Do Don't
The message window appears. The message window is displayed.
You can test notifications using... Testing notifications can be done using...
The catalog is imported. You have imported the catalog.

Tenses

  1. Do not use the future tense in the documentation. We only talk about what is, not what will be, so most sentences should be written in the present tense.
  2. The past is possible in certain cases but should be kept to a minimum.
  3. Do not use might / shall / ought / could. Knowing things that only might happen is not helpful.
Type Do Don't Comments
Future Click ABC to start the import. Click ABC and the import will start When?
Future Define a filter. You will now define a filter. now is useless, especially mixed with a future tense (is it now or later?)
Future Click ABC... You will need to click ABC...
Title Configure the service Configuring the service
Title Add a user To add a user
Uncertainty The process starts in 20 seconds. The process might start in 20 seconds. Might leads to more questions: What happens if it doesn't? How sure is this?

Capitalization

Always capitalize product and feature names.

Also use a capital letter after colons (:)

  • Your plan: Standard
  • Note: This is my note.

Titles

  1. Don't use questions as titles. Example: How does it work?
  2. Use sentence capitalization (only the first letter is capitalized).
  3. If you have a verb in your title, use the imperative form.
  4. Don't use a CTA-style title, use articles rigorously.
Type Usage Example
Title without a verb Section explaining what something is. Database sharding
Title with a verb Usually section explaining how to do something. Create a service, Delete a pool
Do Don't Comments
Delete user Delete a user Do not use CTA-style titles.

Links

You have 2 ways to link to a page:

  1. The link text is the title of the target page.
  2. The link text is the action of the sentence.

Anything else is generally inefficient and more difficult to read.

Example Do Don't
Using the title To learn more about API documentation, see API reference. Click here to see the API docs.
Call to action Before you start, install ABC. Before you start, you can read this page.

Tasks and steps

  • Prefix opttional steps with Optional:.
  • Use step results only when necessary.
  • Click chains start with the first click in the UI, not the last click.
Example Do Don't
Click chains Click File > Save > OK Click Save > OK from the File menu.

Full stops

Full stops are used to mark the end of a sentence. A sentence is a group of words with a least one verb (and a subject unless the verb is in the imperative/participle form). If you use a sentence, even in a list, use a full stop.

The exception to the rule are titles. They can sometimes be sentences, but do not take a full stop. For example, dialog titles or section titles:

  • Action required
  • Confirm selection
  • Integrating with the product

Writing UI instructions

  • Use click for buttons.
  • Use select for checkboxes, radio buttons, item in dropdown lists.
  • Use short click chains in the order of the UI.
Example Do Don't
Short click chains Click Action > Delete. Click Delete in the Actions menu.

Quotes, bold, italics, and inline code

Never use double-quotes (") or single quotes (') for anything. Instead, use the following style in the right context:

  • Bold (**word**): for UI elements or calls to action, and strong emphasis.
  • Italics (_word_) for other cases. Use italics rarely.
  • Inline code (`word`) for technical values or technical values to type.
Example Do Don't
UI element Click Account > Settings. Click "Account" and "Settings".
Code Set db_id to ABC. Set the "db_id" parameter to ABC.
Strong emphasis Do not click Delete. Do not click Delete.

Politeness

Do not use please or any unnecessary politeness.

Trademarks

  1. Ensure the registered trademark symbol (®) is used with service names, at least for their first occurrence within the documents.
  2. Use complete service names, like Aiven for Apache Flink, instead of Apache Flink when referring to anything specific to Aiven for Apache Flink.

Documentation text styles

Information type Style
Interface element Bold (**)
User input Code (`)
Quotes Italics (_)