Technical Writing Style Guide
Consider these guidelines when writing technical documentation. This page will be in flux as requirements and situations change.
- Inform (educate) the user.
- Write clearly, using words the audience understands.
- Compose simple, active voice sentences.
- Understand the audience and speak directly to the reader.
- Determine if the text requires a change in grammatical person or past tense, future tense, and/or declarative mood.
- Avoid unnecessary repetition, redundant jargon, and passive voice.
- Evaluate your writing: write, review, and repeat.
US or UK English?
We use US English. Center instead of centre. Color instead of colour. Behavior instead of behaviour.
For more details and word lists you can search the web.
Important information first
Try to put the important information towards the beginning of the sentence. If possible, state the purpose of the action before stating the action, so the reader can skip the instruction if the purpose doesn't apply.
- To enable quick and easy integration with third party tools and workflows Proxmox VE offers a RESTful API.
- Proxmox VE offers a RESTful API to enable quick and easy integration with third party tools and workflows.
- Click Delete if you want to delete the entire document.
- To delete the entire document, click Delete.
Use short sentences. In general, an average of 15 to 20 words is effective for most technical communication. Long sentences tax the brain more and make it more difficult to write, read, and understand information.
Sentence length affects the quality of the writing. Try to vary the length and beginnings of sentences to keep the reader focused. A sentence that list three or more items may work better as a bullet list.
Test the readability of your text or highlight complex sentence structures with online tools, for example https://www.hemingwayapp.com
- Are words or phrases, sometimes whole paragraphs, that connect one idea together.
- Use transitions to clarify the relationships between ideas.
- Sometimes simply adding for example or in other words at the beginning of a sentence will improve the flow of ideas.
|To add to a previous point.||and, or, nor, furthermore, indeed, also, moreover, in fact, first, second, in addition|
|To follow or precede an idea.||see Procedures...|
|To illustrate or expand on a point||for instance, for example, for one thing, similarly, likewise|
|To summarize or emphasize a point.||therefore, thus, so, and so, hence, consequently, on the whole, all in all, in other words, in short, in conclusion|
|To qualify or illustrate a point||frequently, occasionally, in general, specifically, in particular, usually|
|To shift to a different point of view or signal a contradiction.||but, however, yet, on the contrary, not at all, surely, no|
|To make a concession.||although, though, whereas|
|To connect an explanation to a statement.||because, as , since, for|
|To qualify and restrict a more general idea.||if, provided, in case, unless, lest, when|
A procedure is a sequence of numbered steps for accomplishing a task or a step-by-step instruction.
- Consider a heading, so readers find instructions quickly. Choose same phrasing style for the headings. Example: "Closing the Program"
- Each step specifies an action. It has to be clear and easy to follow. It should answer the question, "What should I do next?" with one meaningful action.
- Use parallel structure.
- Use imperative verb form (telling the reader what to do).
|Transitions for procedures|
|To follow or precede an idea.||first (second, third), then, next, after, before, since, as, when, while, subsequently, prior to, preceding this, previously, simultaneously, following, later, earlier, as soon as, during, until, once...|
You can introduce a procedure with an introductory sentence, providing additional context (without repeating the heading).
- Example: To do this with something, follow these steps:
Use a bullet if the procedure includes only one single step.
Closing the Program
- To close the program, choose Exit on the File menu.
Label sub-steps in a numbered procedure with lowercase letters, and sub-sub-steps with lowercase Roman numerals.
1. First, do foo, as follows:
- a. Do the first part of foo.
- b. Do the second part of foo. There is no third part.
- i. Do the first sub-part of foo part two.
- ii. Do the second sub-part of foo part two.
2. Next, do bar.
If the user must press Enter after a step, then include that instruction as part of the step.
- 1. Click the search box, then type custom function.
- 2. Press Enter.
- 1. Click the search box, then type custom function and press Enter.
State the purpose of the action before stating the action.
- Click File > New > Document to start a new document.
- To start a new document, click File > New > Document.
Technical writing is information delivery. Keep it simple and to the point.
- Avoid elaborate prose.
- Avoid padding.
- Avoid pomp, use simple words. Most of our audience are non-native English speakers.
- Avoid verbosity.
Each word should contribute meaning to the sentence.
Use Active Voice
Active voice clearly shows the actor in a situation. When we read active voice, we know who does what to whom. Active voice is shorter and more interesting to read. Active voice is the standard for technical writing.
- A. They speak English.
- B. English was spoken.
Passive voice obscures the actor—sometimes deliberately, as in, "Mistakes were made." Passive voice is ambiguous and often leaves out important information. Who made those mistakes?
- The file is edited by the administrator.
- The administrator edits the file.
You can identify the passive voice easily. Sentences that have the word "by" are almost always passive. Past-participle verbs ("was eaten", "is driven") are usually passive. You can often easily rework a passive sentence to turn it active. Just put the actor first.
- This Wiki has been written by various authors.
- Mistakes were made.
- One must masticate thoroughly to ensure the burrito will have been eaten completely.
- Various authors wrote this Wiki.
- I made a mistake.
- Chew the burrito well.
Person and Mood
Depending on the kind of documentation (descriptions or instructions) it is best to use different persons/moods.
- Third-person indicative mood (used in descriptions)
- Second-person imperative mood (used to give instructions)
- Avoid first person
Third person indicative mood
- Use this person/mood to write descriptions, to introduce a feature or a technology.
- Use this mood whenever you are telling the reader about what happens, but not giving instructions.
- The writer tells the reader about something but does not address the reader directly.
- A technician inserts the memory card into the card slot.
Don't use "one" as pronoun. This is UK English, and sounds too formal for US English.
Second person imperative mood
- Give instructions directly, if possible with imperative
- Don't use modal verbs (should, could, might).
- Use this person/mood to tell the reader directly to do something as if giving an order or instruction (in present tense).
- It is OK to use the pronoun "you" in general description. It is by no means unprofessional. In fact, it helps you to write easier sentences. Which then simplifies comprehension for the reader.
- Insert the memory card into the card slot.
- To create a container... (is better than "You can create a container by...")
Give instructions like:
- do this
- do that
- use command xyz
- click button
Avoid first person
- Never use first-person singular (I, me).
- Try to avoid first-person plural (we) if possible. When writing about Proxmox (the company) or a project (Proxmox VE, Proxmox Backup) try to avoid the use of "we".
We implemented two virtualization technologies.
Proxmox VE supports two virtualization technologies.
It's OK to use "we recommend" if the sentence would be too complicated otherwise.
Titles and Headlines
For titles, first and second hierarchy headlines (1 & 1.1) use title-style capitalization. For all other hierarchies use sentence-style capitalization.
- Always capitalize the first and last word.
- A Home to Go Back To
- Don't capitalize a, an, or the unless it's the first word.
- Proxmox on the Issue
- Don't capitalize prepositions of four or fewer letters (such as on, to, in, up, down, of, and for) unless the preposition is the first or last word.
- How to Install Proxmox VE
- Don't capitalize and, but, or, nor, yet, or so unless it's the first word or the last word.
- Monitoring and Operating a Proxmox VE Cluster
- Capitalize all other words, including nouns, verbs (including is and other forms of be), adverbs (including very and too), adjectives, and pronouns (including this, that, and its).
- Teaching Math Over and Over Again, in Less Time Than Before
- Capitalize the second part of a hyphenated compound if it would be capitalized without the hyphen or it's the last word.
- Hyper-Converged Infrastructure
- Capitalize the first word of labels and terms that appear in UI and APIs unless they're always lowercase (for example, "fdisk").
See also https://titlecaseconverter.com/
Use sentence-style capitalization in most titles and headings: capitalize the first word and lowercase the rest.
Exceptions Proper nouns, including brand, product, and service names, are always capitalized. If a title or heading includes a colon, capitalize the first word after it.
- Watch your favorite HD movies, TV shows, and more
- 1 TB of cloud storage
- Choose the cluster size that is right for you
- Running a hyper-converged infrastructure with Proxmox VE
- Network: Setup and configuration
If a sentence contains more than a comma or two and ending punctuation, consider rewriting it to make it crisp and clear.
Use a comma
- Oxford (or serial) comma: Use Oxford commas for clarity, when separating items in a list of three or more items.
- "We invited the dancers, John, and David." - In this case, John, David and the dancers were invited.
- "We invited the dancers, John and David." - Here, John and David are the names of the invited dancers.
- Use a comma before any coordinating conjunction (and, but, for, or, nor, so, yet) that links two independent clauses.
- "I went running, and I saw a duck." - Two independent clauses because two times the subject "I".
- "I went running and saw a duck." - Only one subject ("I") - no comma.
- Following an introductory phrase/introductory adverbs.
- How to recognize an adverb: Many adverbs end in "ly" and answer the question "how?" (however, on the other hand, furthermore, meanwhile, suddenly).
- "With the app, you can call any phone."
- "Finally, I went running."
- Use a comma after sequence words.
- Sequence words usually introduce a sentence. They are used in procedural texts to signal the order of steps. When we write sequence words like first, next, then, or last, we put a comma after those words.
- "First, pour milk into a bowl."
- "Then, add some freshly washed strawberries to the bowl."
- "After that, peel an apple and core it."
- Use a comma after a dependent clause that starts a sentence (when, after, although, as, because, before, once, since, while).
- "When I went running, I saw a duck."
- Use a comma between two adjectives that modify the same noun.
- "I saw the big, mean duck when I went running."
Don't use a comma
- To join independent clauses when you don't use a conjunction. (Use a semicolon instead.)
- "Select Options; then select Enable fast saves."
- Between verbs in a compound predicate (when two verbs apply to a single subject).
- "The program evaluates your computer system and then copies the essential files to the target location."
More details: https://www.grammarly.com/blog/comma/
Use a forward slash to imply a combination. Capitalize the word after the slash if the word before the slash is capitalized.
- client/server or Client/Server
Don't use a slash as a substitute for "or", like product/service. Use "or" to describe the action in text (product or service).
Hyphenate two or more words that precede and modify a noun as a unit if:
- Confusion might result without the hyphen.
- read-only memory, built-in drive
- command-line vs. command line
- Two words as a noun. Hyphenate as an adjective, e.g. command-line tool, Linux command line (Source: Microsoft style guide)
- One of the words is a past or present participle (a verb form ending in -ed or -ing and used as an adjective or noun).
- left-aligned text, well-defined schema
- The modifier is a number or single letter plus a noun or participle.
- two-sided arrow, 5-point star
Hyphenate compound nouns when one of the words is abbreviated.
- e-book, e-commerce, e-bike
Use an em dash (—) to set off a parenthetical phrase with more emphasis than parentheses provide. Don’t add spaces around an em dash.
- The information—numbers, configuration, and text—is stored in a container.
By using bullet or numbered lists you can write in a concise and cut to the chase manner. In a list make every point essential and impactful.
When to create a list:
- If you find, within running text, three or more items in a row, pull them out of the paragraph and format them as a list.
- Use a bullet list if the items are options, with no required order.
- Use a numbered list if the user should perform or read the items in a specific order.
- Keep it simple and short.
- If items contain two parts, such as term and definition, boldface the first part, and plaintext the second part.
- If items contain links and descriptions, put the link first, and indent the description underneath it.
Do not mix and match.
Keep the style within a list. Either full sentences with punctuation or phrases/fragments without punctuation. Use capitalization. Or at least keep your style consistent in a list/text.
- If all bullets are full sentences - end each one with a period (full stop).
- If all bullets are full sentences - end each one with a period (full stop).
- Bullets are phrases or fragments - no end punctuation
- Bullets are phrases or fragments - no end punctuation
Avoid Slang, Jargon, and Idioms
Don't use jargon, slang, and idioms if there is a more familiar term available.
Symbol instead of glyph.
Stick to one term if multiple are possible. Switching back and forth between multiple terms can confuse the reader. Add other possible terms the first time you use it. This helps users who search for another term.
- USB flash drive
- USB stick
- USB media
- Use in a sentence
A USB flash drive (USB stick) is the recommended way to install Proxmox VE.
|mainboard, main board||motherboard|
|USB/usb stick/drive, flash drive, thumb drive||USB flash drive|
|Web UI, WebUI, webinterface||web interface, GUI, or web UI|
Common contractions are okay to use like:
Do not use contractions with verbs and nouns.
Proxmox's the leading open-source virtualization company.
Proxmox is the leading open-source virtualization company.
Always avoid abbreviations out of laziness.
- 'approx.' for 'approximately' (better write 'about')
- 'etc.' - etc. is often misused. Avoid it.
- Example for etc.
“He eats lots of fruit, such as apples, oranges, bananas, etc.” - The ‘etc.’ here is redundant because of the ‘such as’.
If you are using ‘etc.’ then the correct way to write the above sentence would be: “He eats lots of fruit: apples, oranges, bananas, etc.”
If possible, avoid using e.g., or i.e., in the Proxmox technical documentation. If you yourself have to look up what it means, also most other readers will not know what it means.
- "for example" (e.g.,) or
- "that is" (i.e.,).
Or use alternative words for exemplification (illustration): as an illustration, especially, including, in detail, in other words, in particular, for example, for instance, namely, specifically, such as, to demonstrate, to explain, to illustrate
Comma: If you have to use e.g./i.e, don't forget the comma at the end and use
- "e.g.," as in "for example" and
- "i.e.," as "in other words"/"that is".
More detailed information can be found here.
When you use an acronym, spell it out the first time with the abbreviation in brackets. Do not use an acronym if you use it only once!
Kernel Samepage Merging (KSM)
Commonly known abbreviations can be used. For example:
Some commonly used abbreviations should be avoided.
You can use the abbreviated VM...
- if you explicitly refer to a UI item in a Proxmox solution.
- if it's not mentioned in an introductory paragraph concerning VMs (for example explaining Qemu/KVM).
You can use the abbreviated CT...
- only if you explicitly refer to a UI item in a Proxmox solution.
Otherwise, use "container".
If you're talking about both VMs and container, use "guest" or "virtual guest".
Should always be written as Proxmox VE/Proxmox Virtual Environment, Proxmox Mail Gateway, and Proxmox Backup Server in formal/public/marketing communication. If you're talking about one of our products, don't use 'Proxmox' alone, as it is our trademark/brand and could also just mean Proxmox, the company. It is not a product.
Examples need to be clear, correct and tested.
It is better to not have any examples than bad ones.
The basic rules of capitalization in English are quite simple:
- Capitalize the first word of a sentence
- Capitalize names and other proper nouns
- Names are proper nouns. The names of cities, countries, companies, religions, and political parties are also proper nouns, so you should capitalize them, too.
- You should also capitalize words like mom and grandpa when they are used as a form of address.
- Capitalize days, months, and holidays, but not seasons
- The names of days, months, and holidays are proper nouns, so you should capitalize them.
- Capitalize cities, countries, nationalities, and languages
- The names of cities, countries, nationalities, and languages are proper nouns, so you should capitalize them.
Use 'an' with nouns that start with a vowel sound (a, e, i, o, u) and 'a' with nouns that start with a consonant sound (letters that are not vowels):
- A chair
- An apple
- A truck
- An orange
- A castle
- An opera
- A historical (an historical is archaic and incorrect at least in the U.S.)
- A Media Gateway Controller
- An MGC (M is pronounced em, so it is a vowel sound)
- An before a silent h: an hour...
- A before u and eu when they make a consonant Y (sound like 'you')
- a European, a university, a unit
The indefinite article:
refers to something for the first time:
An MGC is a "Media Gateway Controller." The MGC controls all activity on an IP phone network.
Industry Related Terms
Always use correct company and product names.
- Proxmox 3.4 (Which product do you mean? Proxmox is not a product)
- the Web
- Proxmox Server Solutions GmbH
- Proxmox VE
- Proxmox Virtual Environment
- Proxmox Mail Gateway
- Proxmox Backup Server 3.1
- the web
- a how-to (guide)
- Ceph Filesystem, Ceph Object Storage, Ceph Block Devices, Ceph Storage Cluster
- 'web interface', web UI (space in-between), 'web-based user interface' or 'GUI'
In technical writing, the gender-neutral pronouns, they, them, or their, are preferable to the verbose he or she/his or her/him or her. If a sentence seems awkward, try to avoid the issue: leave out the pronoun or use second person imperative.
Data: singular or plural?
'Data' is accepted both as a singular and a plural noun. While the plural form is more formal, we use it as a singular noun to stay consistent with existing Proxmox documentation. See Merriam Webster for a more in-depth explanation and examples.
This guide is loosely adapted from the following resources: