This module outlines clear guidelines on grammar, punctuation, and writing mechanics to ensure clarity, consistency, and quality in your documentation.
Sentence structure
1. Use active voice
Active voice makes sentences clearer because the subject (the main doer) performs the action (the verb). This helps readers immediately understand who is doing what, which improves clarity in instructions and technical documentation.
Example: The system (subject) sends (action/verb) an email notification (object). This structure is direct, easy to read, and preferred in most technical writing.
Recommended: The system sends an email notification.
Not recommended: An email notification is sent by the system.
Use active voice in instructions, processes, and descriptions to enhance reader understanding. Passive voice (Object → Verb → Subject) is acceptable when the action is more important than the subject or when the subject is unknown (e.g., 'Your account was blocked by the system.').
2. Maintain subject-verb agreement
Ensure the subject and verb agree in number.
Recommended: The list of articles is displayed.
Not recommended: The list of articles are displayed.
For collective nouns, consider whether the group acts as a unit (singular) or individuals (plural).
3. Avoid sentence fragments
Each sentence must have a subject and a verb.
Recommended: Document360 provides multiple features.
Not recommended: Providing multiple features.
Fragments often occur after bullet points or in complex lists. Ensure completeness.
4. Use parallel structure
Maintain parallelism when listing items.
Recommended: Document360 allows users to create, edit, and publish articles.
Not recommended: Document360 allows users to create, editing, and publish articles.
Ensure verbs in lists share the same tense and form.
5. Keep sentences concise
Avoid unnecessary words.
Recommended: Document360 helps you manage content.
Not recommended: Document360 is a tool that helps you to manage your content.
Avoid unnecessary filler words that add length without adding meaning (for example, ‘in order to’ or ‘that’).
Punctuation
1. Serial commas
Use serial commas in lists.
Recommended: Document360 supports categories, articles, and templates.
Not recommended: Document360 supports categories, articles and templates.
The serial comma avoids ambiguity.
2. Quotation marks
Place punctuation inside quotation marks.
Example: Click “Save.”
Use double quotes for direct speech and single quotes for quotes within quotes.
Example: “Select ‘Profile’ from the top navigation bar.”
3. Apostrophes
Use apostrophes for possessives and contractions.
Recommended: The article's title is clear.
Not recommended: The articles title is clear.
Do not use apostrophes for plural nouns (e.g., features not feature's).
4. Colons
Use colons to introduce lists, explanations, or quotes.
Example: The options are: Save, Edit, and Delete.
Do not capitalize after a colon unless it's a proper noun or complete sentence.
5. Dashes and hyphens
Hyphen (-): Joins words in compound terms and compound modifiers.
En dash (–): Indicates number ranges.
Em dash (—): Adds emphasis or an aside, and is used without spaces
Examples:
Single sign-on (hyphen)
2010–2020 (en dash)
Note—this is important. (em dash)
6. Ellipses
Use ellipses for omissions or trailing thoughts, with no spaces before or after.
Example: It is important...
Use sparingly and avoid in titles or headers.
7. Exclamation points
Use sparingly and never more than one at a time.
Recommended: Your profile is all set!
Not recommended: Payment failed! Please try again later.
Avoid using in failure messages or alerts.
Capitalization
Use sentence case for headings, titles, and all content except for UI elements, feature names, proper nouns, and product names.
Recommended: Managing categories in Document360
Not recommended: Managing Categories in Document360
Avoid unnecessary capitalization for emphasis.
Numbers
Use numerals for 10 and above, spell out below 10.
Example: three steps; 15 users.
Use commas in numbers with four or more digits (e.g., 1,000).
Use numerals for measurements, dates, and technical specifications.
Abbreviations and acronyms
Spell out terms on first mention with the acronym in parentheses.
Example: Content management system (CMS)
Use the acronym alone after the first mention.
Example: The CMS supports role-based access and version control.
Avoid overusing acronyms. Ensure readers understand the acronym before using it extensively.