Grammar and punctuation
Grammar and punctuation rules are well-documented in the Google Developer Documentation Style Guide and the Chicago Manual of Style. This style guide does not attempt to reproduce their efforts, which you can consult. Instead, this page documents common topics and exceptions that occur regularly in writing Lucidworks documentation.
Grammar
Write all documentation in American English.
Do not use first person in documentation.
- Exception
-
You may use first person when writing FAQs and in the question of the
TIP.faqadmonition.
When using an unfamiliar abbreviation, spell out the abbreviation and include the abbreviation the first time. Do not start a sentence with an abbreviation.
- Recommended
-
✅ The Parallel Bulk Loader (PBL) supports…
- Not recommended
-
✘ PBL supports…
Do not capitalize internet unless it starts a sentence or would otherwise be capitalized. Do not hyphenate email.
Use English abbreviations over Latin abbreviations. Avoid abbreviations such as i.e., e.g., and etc.
Avoid slang abbreviations such as tl;dr, YMMV, and others. Write what you mean in a way that does not use slang.
Use the formal name of a specific file type.
- Recommended
-
✅ Import your CSV file.
- Not recommended
-
✘ Import your .csv file.
✘ Import your
.csvfile. - Exception
-
If the file extension is important in the context of the article, use code format for the file extensions. See Web data source for an example.
Punctuation
Use the serial comma.
- Recommended
-
✅ You can create, edit, and delete users in Springboard.
- Not recommended
-
✘ You can create, edit and delete users in Springboard.
Do not use an apostrophe to create a plural, even if you are making an abbreviation plural.
- Recommended
-
✅ APIs
- Not recommended
-
✘ API’s
Use 's at the end of singular possessives ending in s.
- Exception
-
Lucidworks' uses only the apostrophe (') in its possessive form.
Contractions
| Do not confuse contractions with possessive forms. |
Contractions such as isn’t and don’t are acceptable but to be used sparingly.
When possible, avoid contractions in article titles and section headers.
Do not use contractions formed from nouns and verbs. These may be confusing to non-English speakers.
- Recommended
-
✅ If Fusion has stopped running…
- Not recommended
-
✘ If Fusion’s stopped running…
Avoid combining more than two words into one contraction, such as shouldn’t’ve (should not have).
Overall, write what feels natural for your documentation. If avoiding a contractions makes your writing more awkward, use the contraction instead of writing around it.
Resources
For general grammar and punctuation information, consult the resources in the style guide’s index page.
The following resources discuss specific grammatical topics:
The following resources discuss specific punctuation topics: