Skip to main content

Writing style

Use fewer words, better. Don't overwhelm users with information. Use concise and clear language and follow the guidelines for content types. Rather than repeating information from another topic, link to it instead.

For topics not covered in this guide, see Google Developer Documentation Style Guide.

Language and grammar

Datagrok documentation should be clear and easy to understand:

Conciseness

Conciseness is about using the fewest words while retaining completeness in meaning. You can achieve conciseness in several ways:

  • Shorten words and phrases.

    WordyShort
    presentlynow
    provide an opportunityallow/permit
    with regard toabout
  • Substitute large and complex words with short, simple words.

    ComplexSimple
    commencebegin/start
    demonstrateshow
    employ / utilizeuse
  • Avoid the words ending in -sion or -tion (nominalizations). Replace them with active words.

    NominalizationActive word
    come to the conclusionconclude / decide
    implementation ofimplement
    take into considerationconsider
  • Omit cliches, idioms, old-fashioned, or overused words.

    Instead ofUse
    at all timesalways
    best-in-classsuperior
  • Avoid word redundancies.

    Instead ofUse
    like for examplelike or for example
    the reason whywhy
    past experienceexperience
  • Avoid sentences starting with there is, here is, it is, and similar (that is, sentences with no true subjects). Use this tips:

    1. First, identify an actor.
    2. Then, find the key action and make it a verb.
    3. Lastly, make the actor the subject of this verb.
    Instead ofUse
    There are many features in the platform.The platform has many features.
    There are multiple options.You have several options.
  • Drop unnecessary words; use shorter alternatives if available.

    Instead ofUse
    It is necessary for you to do A.You must do A.
    Follow all of the steps below.Follow the steps below.

    Tip: If a step is optional, start with the word optional followed by a period. For example: Step 3. Optional. Change the size by dragging the bottom right corner.

  • Simplify long, complicated sentences.

    • Look for and remove an introductory phrase that doesn't add value.
    Instead ofUse
    As discussed previously, you can embed a viewer as an iframe.You can embed a viewer as an iframe.
    It is important to note that this feature is in beta.Important: This feature is in beta.
    • If a sentence contains multiple prepositions, rewrite the sentence to remove as many prepositions as you can.
    Instead ofUse
    These representations can be of great importance for the description of monomers of a decomposed macromolecule.These representations are essential to describing monomers of a decomposed macromolecule.

Active voice

Avoid using passive voice. When you use passive voice, you imply that the doer of the action is unknown, unimportant, or cannot be named for any reason. Because technical writing is action-oriented, the use of active voice is preferred. Never end a sentence with a passive word. Place the subject and verd close to each other and put them at the front of a sentence.

Instead ofUse
In this article, challenges in interactive data exploration are discussed.This article addresses challenges in interactive data exploration.
A dialog is displayed on clicking the icon.When you click the icon, a dialog opens.
Viewers can be customized.You can customize viewers.

Pronouns

Use the second person point of view (you) instead of a third person point of view (he/she). If you must use the third person, use plural pronouns (they, their) instead of single pronouns (he/she, his/her).

Note: Avoid using words that explicitly favor one gender, such as guys or businessman/businesswoman.

Words that minimize the difficulty

Avoid using words that minimize the difficulty involved in a task or operation, such as just or simply. People may become frustrated when they do not find a step as straightforward or simple as it is implied to be.

Capitalization

Use sentence case. Sentence case refers to a capitalization style in which only the first word and proper nouns or acronyms are uppercased:

  • Capitalize names of third party organizations and products (such as Slack), methods, or methodologies (such as Agile).

  • For headings, capitalize the first word only.

  • When referring to specific user interface text, like a menu item, use the same capitalization that the user interface shows.

  • For bulleted lists, always capitalize the first word, including the text that completes an explanatory or introductory text (ending with a colon). For example:

    You have several options:

    • First option
    • Second option

Compound words and words with prefixes

We tend to use the closed form of compound words and words with prefixes; that is, write these words without a space or a hyphen (for example, a dataset or an open source plugin). For the list of commonly used terms, see Word list.

Contractions

You can use most types of contractions. Negation contractions (such as isn't or don't) are even helpful because it's harder to misread don't compared to do not. However, avoid contractions formed from nouns and verbs:

Instead ofUse
The platform's fast and easy to use.The platform is fast and easy to use.

Acronyms and numbers

If you use an acronym, spell it out on the first use on a page. You don't need to spell it out more than once on a page. If you can, avoid using acronyms in headings.

When using numbers in the text, spell out zero through nine, and use numbers for 10 and greater. For more guidance, see Google Developer Documentation Style Guide.

Clause order

When giving instructions, follow this clause order:

  1. goal first
  2. then location
  3. then action

Mentioning the goal or circumstance first lets the user skip the instruction if it doesn't apply.

Instead ofUse
Click Remove on the Sidebar to delete the document.To delete the document, on the Sidebar, click Remove.

Paragraphs

The first sentence of a paragraph is a topic sentence describing that paragraph's central idea. State that idea upfront, then build on it. When reading technical documentation, users often look for a specific piece of information. When they know the topic, users can skip the paragraph if that paragraph's information is irrelevant to their needs.

Never assume users have read every word in the preceding paragraph. Don't start a paragraph with a pronoun or words like but or however. Every paragraph should encapsulate an idea that can stand on its own.

Follow the 1:1 rule: one paragraph, one idea. Remove any sentences that neither clarify the idea in that paragraph, nor logically connect this paragraph and the next.

End the paragraph with a sentence that summarizes the topic sentence.

Punctuation

Follow these guidelines for punctuation:

  • Don't use semicolons or dashes. Use two sentences instead.

  • In a list of three or more items, use Oxford commas before the final and or or.

  • Don't use curly quotes. Use straight quotes instead.

  • For bulleted lists:

    • Don't add commas or semicolons to the ends of list items.

    • If a list item is a complete sentence (with a subject and a verb), add a period in the end.

    • Use no punctuation after bullets that are not complete sentences.

    • Be consistent. Don't mix sentences and individual items in a list.

    • Separate list items from introductory or explanatory text with a colon. Also, for numbered lists, italicize the numbered list items to make them visually stand out.

      For example:

      This procedure has two steps:

      • Step 1. Do the first thing.
      • Step 2. Do the second thing.

Commas and appositives

An appositive is a noun or a phrase placed next to another noun or a phrase to modify it. Appositives can be restrictive and nonrestrictive. The following table summarises the use of commas with appositives:

RestrictiveNonrestrictive
PurposeNarrow down the meaningProvide additional information
When removedMeaning changesMeaning doesn't change
Comma usageDon't wrap in commasWrap in commas
ExampleOnly users who have preinstalled the package can access this feature.Data augmentation, oneof the platform capabilities, is used to push insights to the users.