The following are general writing guidelines for all Capriola Cloud technical documentation, including release notes.
Ensure that you use the US English spelling for words.
Write in active voice and present tense. Consider who or what is doing the action: the human or the computer.
Active voice: Be sure to send all requests over SSL to a valid URL.
Avoid passive voice, past tense, and future tense.
For verbs, use the root form or third-person singular (-s or -es) form. Avoid -ing constructions, especially for chapter titles and section headings, which can be difficult to translate in certain languages.
Use:
- Your user administrator creates the CSV User Import file.
- Be sure to save the file to a secure location.
Avoid:
- Creating the CSV User Import File
- Clicking the Save button will add a new user.
Spell out numbers zero through nine and use numerals for all other numbers. The exception to this is to use numerals when the numbers are joined by a hyphen:
1-100 items
Put one space between a measurement and its unit:
1000 KB
Capitalize the proper name of features and functionality:
Capriola Cloud Notations functionality
When deciding between a and an, consider the sound that immediately follows. Vowel sounds require an. Consonant sounds require a. Exceptions to this are certain words that start with the letter h and terms that can be pronounced either as a word (acronym) or by each letter (initialism).
• an hour, an historic event
• a SQL (see-quel) server or an SQL (es-que-el) server
Avoid Latinisms, older English words, and certain symbols used in place of words. Use the modern English equivalent or revise the sentence. Refer to the table below for specific examples.
| Avoid | Use |
|---|---|
| ampersand (&) | and, unless the & is part of a formal name or title |
| forward slash (/) | Revise the sentence. A forward slash is generally used in place of or to indicate a choice, such as and/or. It is also used as an and or to indicate a relationship between two words, such as b/w for black and white or n/a for not applicable. |
| e.g. | for example |
| i.e. | that is |
| etc., etcetera, &c. | Revise the sentence. For example, change sentence word, word, etc. to sentence, such as word and word. |
| thus, thereby, therefore, and similar words | Modern English equivalent |
Enter a single space after all punctuation marks, including periods.
For clarity, use serial commas for sentences or fragments that include three or more items and a conjunction.
- Without serial comma: Capriola Cloud Notations functionality lets you add, edit and delete your notations.
- With serial comma: Capriola Cloud Notations functionality lets you add, edit, and delete your notations.
Check your work with a virtual online editor, such as Hemingway: http://www.hemingwayapp.com