Style and language
Use fewer words, better. Don't overwhelm users with information. Use concise and clear language. 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:
- Write in US English with US grammar.
- Be clear and concise.
- Use active voice: make it clear who's performing the action.
- Put conditional clauses before instructions, not after.
- Use the second person point of view.
- Don't use words that minimize the difficulty of a task.
- Use sentence case for headers and bulleted lists.
- Write compound words and words with prefixes without hyphens or spaces.
- Contractions are OK because we write in an informal tone.
- Spell out: acronyms on first use and numbers from zero to nine.
- For usage and spelling of specific words, see the Word list.
Conciseness
Conciseness is about using the fewest words while retaining completeness in meaning. You can achieve conciseness in several ways:
Shorten words and phrases.
Wordy Short presently now provide an opportunity allow/permit with regard to about Substitute large and complex words with short, simple words.
Complex Simple commence begin/start demonstrate show employ / utilize use Avoid the words ending in -sion or -tion (nominalizations). Replace them with active words.
Nominalization Active word come to the conclusion conclude / decide implementation of implement take into consideration consider Omit cliches, idioms, old-fashioned, or overused words.
Instead of Use at all times always best-in-class superior Avoid word redundancies.
Instead of Use like for example like or for example the reason why why past experience experience Avoid sentences starting with there is, here is, it is, and similar (that is, sentences with no true subjects). Use this tips:
- First, identify an actor.
- Then, find the key action and make it a verb.
- Lastly, make the actor the subject of this verb.
Instead of Use 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 of Use 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 of Use 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 of Use 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 verb close to each other and put them at the front of a sentence.
| Instead of | Use |
|---|---|
| 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 of | Use |
|---|---|
| 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:
- goal first
- then location
- then action
Mentioning the goal or circumstance first lets the user skip the instruction if it doesn't apply.
| Instead of | Use |
|---|---|
| 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.
Try to limit paragraphs to 4-5 sentences. 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.
Punctuation
Follow these guidelines for punctuation:
Punctuation is placed outside of quotation marks, British English style. For everything else (dates, times, spelling), we use American English style.
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 summarizes the use of commas with appositives:
| Restrictive | Nonrestrictive | |
|---|---|---|
| Purpose | Narrow down the meaning | Provide additional information |
| When removed | Meaning changes | Meaning doesn't change |
| Comma usage | Don't wrap in commas | Wrap in commas |
| Example | Only users who have preinstalled the package can access this feature. | Data augmentation, one of the platform capabilities, is used to push insights to the users. |