Technical Writing Style Guide

Consider these guidelines when writing technical documentation. This page will be in flux as requirements and situations change.

Goals

• 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.

Sentence Structure

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.

Bad

To enable quick and easy integration with third party tools and workflows Proxmox VE offers a RESTful API.

Good

Proxmox VE offers a RESTful API to enable quick and easy integration with third party tools and workflows.

Bad

Click Delete if you want to delete the entire document.

Good

To delete the entire document, click Delete.

Sentence length

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

Transitions

• 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.

Uses	Transitions
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

Procedures

A procedure is a sequence of numbered steps for accomplishing a task or a step-by-step instruction.

Format

• 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...

Introductory sentence

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:

Single-step procedure

Use a bullet if the procedure includes only one single step.

Example

Closing the Program

• To close the program, choose Exit on the File menu.

Numbered procedures

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.

More guidelines

If the user must press Enter after a step, then include that instruction as part of the step.

Bad

1. Click the search box, then type custom function.

2. Press Enter.

Good

1. Click the search box, then type custom function and press Enter.

State the purpose of the action before stating the action.

Bad

Click File > New > Document to start a new document.

Good

To start a new document, click File > New > Document.

More details, see http://www.webwritingthatworks.com/CPATTERNprocedures.htm or https://developers.google.com/style/procedures

Concise Communication

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.

Active

A. They speak English.

Passive

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?

Passive

The file is edited by the administrator.

Active

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.

Passive

This Wiki has been written by various authors.

Mistakes were made.

One must masticate thoroughly to ensure the burrito will have been eaten completely.

Active

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.

Example

A technician inserts the memory card into the card slot.

Bad

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.

Example

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".

Bad

We implemented two virtualization technologies.

Good

Proxmox VE supports two virtualization technologies.

Exception

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.

Title-style capitalization

• Always capitalize the first and last word.

Example

A Home to Go Back To

• Don't capitalize a, an, or the unless it's the first word.

Example

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.

Example

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.

Example

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).

Example

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.

Example

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/

Sentence-style capitalization

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.

Examples

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

Punctuation

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.

Compare

"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.

Example

"I went running, and I saw a duck." - Two independent clauses because two times the subject "I".

But

"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).

Example

"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.

Example

"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).

Example

"When I went running, I saw a duck."

• Use a comma between two adjectives that modify the same noun.

Example

"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.)

Example

"Select Options; then select Enable fast saves."

• Between verbs in a compound predicate (when two verbs apply to a single subject).

Example

"The program evaluates your computer system and then copies the essential files to the target location."

More details: https://www.grammarly.com/blog/comma/

Slashes

Use a forward slash to imply a combination. Capitalize the word after the slash if the word before the slash is capitalized.

Example

• client/server or Client/Server
• TCP/IP

Don't use a slash as a substitute for "or", like product/service. Use "or" to describe the action in text (product or service).

Hyphens

Hyphenate two or more words that precede and modify a noun as a unit if:

• Confusion might result without the hyphen.

Example

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).

Example

left-aligned text, well-defined schema

• The modifier is a number or single letter plus a noun or participle.

Example

two-sided arrow, 5-point star

Hyphenate compound nouns when one of the words is abbreviated.

Example

e-book, e-commerce, e-bike

But

email

Em Dashes

Use an em dash (—) to set off a parenthetical phrase with more emphasis than parentheses provide. Don’t add spaces around an em dash.

Example

The information—numbers, configuration, and text—is stored in a container.

Lists

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.

Example

With punctuation:

• 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).

Without punctuation:

• 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.

Example

Symbol instead of glyph.

Consistency

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.

Example

• 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.

Table of used words

Instead of	Use
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

Contractions

Common contractions are okay to use like:

• it’s
• you’re
• that's
• don’t

Do not use contractions with verbs and nouns.

Bad

Proxmox's the leading open-source virtualization company.

Good

Proxmox is the leading open-source virtualization company.

Abbreviations

Always avoid abbreviations out of laziness.

Bad

• 'approx.' for 'approximately' (better write 'about')

• 'etc.' - etc. is often misused. Avoid it.

Example for etc.

Bad

“He eats lots of fruit, such as apples, oranges, bananas, etc.” - The ‘etc.’ here is redundant because of the ‘such as’.

Good

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.”

e.g./i.e.

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.

Simply write

• "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.

Acronyms

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!

Example

Kernel Samepage Merging (KSM)

Commonly known abbreviations can be used. For example:

• USB
• HTML
• URL
• FAQ

Special cases

Some commonly used abbreviations should be avoided.

VM

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).

CT

You can use the abbreviated CT...

• only if you explicitly refer to a UI item in a Proxmox solution.

Otherwise, use "container".

Guest

If you're talking about both VMs and container, use "guest" or "virtual guest".

PVE/PMG/PBS

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

Examples need to be clear, correct and tested.

It is better to not have any examples than bad ones.

Capitalization

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.

A/an

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)

NOTE

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.

Bad

• ProxMox
• Proxmox 3.4 (Which product do you mean? Proxmox is not a product)
• HOWTO
• html
• openvz
• centos
• ceph
• VMWARE
• the Web
• webUI

Good

• Proxmox Server Solutions GmbH
• Proxmox VE
• Proxmox Virtual Environment
• Proxmox Mail Gateway
• Proxmox Backup Server 3.1
• the web
• a how-to (guide)
• OpenVZ
• CentOS
• VMware
• Ceph
• Ceph Filesystem, Ceph Object Storage, Ceph Block Devices, Ceph Storage Cluster
• 'web interface', web UI (space in-between), 'web-based user interface' or 'GUI'

Gender

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.

References

This guide is loosely adapted from the following resources:

• Wikiversity - Technical writing style
• Microsoft Writing Style Guide
• Grammarly capitalization rules