Technical Writing Style Guide: Difference between revisions

From Proxmox VE
Jump to navigation Jump to search
(Created page with " Consider these guidelines when writing technical documentation. This page will be in flux as requirements and situations change. == Goals == *Inform (educate) the user. *...")
 
m (some missing commas, title-case for first two heading levels, syntax nits)
Line 24: Line 24:
For more details and word lists you can search the web.
For more details and word lists you can search the web.


== Sentence structure ==
== Sentence Structure ==


=== Important information first ===
=== 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.
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:
;Bad:
Line 84: Line 84:
==== Format ====
==== Format ====


* Consider a heading so readers find instructions quickly. Choose same phrasing style for the headings. Example: "Closing the Program"
* 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.
* 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 parallel structure.
Line 112: Line 112:
==== Numbered procedures ====
==== Numbered procedures ====


Label sub-steps in a numbered procedures with lowercase letters, and  
Label sub-steps in a numbered procedure with lowercase letters, and  
sub-sub-steps with lowercase Roman numerals.
sub-sub-steps with lowercase Roman numerals.


Line 142: Line 142:
or https://developers.google.com/style/procedures
or https://developers.google.com/style/procedures


== Concise communication ==
== Concise Communication ==


Technical writing is information delivery. Keep it simple and to the point.
Technical writing is information delivery. Keep it simple and to the point.
Line 153: Line 153:
Each word should contribute meaning to the sentence.
Each word should contribute meaning to the sentence.


== Use active voice ==
== 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 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.
Line 181: Line 181:
:Chew the burrito well.
:Chew the burrito well.


== Person and mood ==
== Person and Mood ==


Depending on the kind of documentation (descriptions or instructions) it is best to use different persons/moods.
Depending on the kind of documentation (descriptions or instructions) it is best to use different persons/moods.
Line 189: Line 189:
*Avoid first person
*Avoid first person


===Third person indicative mood===
=== Third person indicative mood ===
*Use this person/mood to write descriptions, to introduce a feature or a technology.  
*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.
*Use this mood whenever you are telling the reader about what happens, but not giving instructions.
Line 200: Line 200:
Don't use "one" as pronoun. This is UK English, and sounds too formal for US English.
Don't use "one" as pronoun. This is UK English, and sounds too formal for US English.


===Second person imperative mood===
=== Second person imperative mood ===
*Give instructions directly, if possible with imperative
*Give instructions directly, if possible with imperative
*Don't use modal verbs (should, could, might).
*Don't use modal verbs (should, could, might).
Line 217: Line 217:
*click button
*click button


===Avoid first person===
=== Avoid first person ===
*Never use first person singular (I, me).
*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".
*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
;Bad
Line 230: Line 230:
It's OK to use "we recommend" if the sentence would be too complicated otherwise.
It's OK to use "we recommend" if the sentence would be too complicated otherwise.


== Titles and headlines ==
== 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.
For titles, first and second hierarchy headlines (1 & 1.1) use title-style capitalization. For all other hierarchies use sentence-style capitalization.
Line 261: Line 261:


* Capitalize the first word of labels and terms that appear in UI and APIs unless they're always lowercase (for example, "fdisk").
* 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 ===
=== Sentence-style capitalization ===
Line 275: Line 277:
:Network: Setup and configuration
:Network: Setup and configuration


==Punctuation==
== Punctuation ==


If a sentence contains more than a comma or two and ending punctuation, consider rewriting it to make it crisp and clear.
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===
=== Use a comma ===


*Oxford (or serial) comma: Use Oxford commas for clarity, when separating items in a '''list of three or more''' items.
*Oxford (or serial) comma: Use Oxford commas for clarity, when separating items in a '''list of three or more''' items.
Line 328: Line 330:
::"I saw the big, mean duck when I went running."
::"I saw the big, mean duck when I went running."


===Don't use a comma===
=== Don't use a comma ===


*To join independent clauses when you don't use a conjunction. (Use a semicolon instead.)
*To join independent clauses when you don't use a conjunction. (Use a semicolon instead.)
Line 343: Line 345:
https://www.grammarly.com/blog/comma/
https://www.grammarly.com/blog/comma/


===Slashes===
=== Slashes ===
Use a forward slash to imply a combination. Capitalize the word after the slash if the word before the slash is capitalized.
Use a forward slash to imply a combination. Capitalize the word after the slash if the word before the slash is capitalized.
;Example
;Example
Line 351: Line 353:
Don't use a slash as a substitute for "or", like product/service. Use "or" to describe the action in text (product or service).
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===
=== Hyphens ===
Hyphenate two or more words that precede and modify a noun as a unit if:
Hyphenate two or more words that precede and modify a noun as a unit if:
*Confusion might result without the hyphen.  
*Confusion might result without the hyphen.  
Line 369: Line 371:
:email
:email


===Em dashes===
=== 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.
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
:;Example
Line 400: Line 402:
*Bullets are phrases or fragments - no end punctuation
*Bullets are phrases or fragments - no end punctuation


== Avoid slang, jargon, and idioms ==
== Avoid Slang, Jargon, and Idioms ==


Don't use jargon, slang, and idioms if there is a more familiar term available.
Don't use jargon, slang, and idioms if there is a more familiar term available.
Line 527: Line 529:
** The names of cities, countries, nationalities, and languages are proper nouns, so you should capitalize them.
** The names of cities, countries, nationalities, and languages are proper nouns, so you should capitalize them.


==A/an==
== 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):
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
*''A'' chair
*''An'' apple
*''An'' apple
Line 549: Line 551:
An MGC is a "Media Gateway Controller." The MGC controls all activity on an IP phone network.
An MGC is a "Media Gateway Controller." The MGC controls all activity on an IP phone network.


== Industry related terms ==
== Industry Related Terms ==


Always use correct company and product names.
Always use correct company and product names.


;Bad
;Bad
*ProxMox
* ProxMox
*Proxmox 3.4 (Which product do you mean? Proxmox is not a product.)
* Proxmox 3.4 (Which product do you mean? Proxmox is not a product)
*HOWTO
* HOWTO
*html
* html
*openvz
* openvz
*centos
* centos
*ceph
* ceph
*VMWARE
* VMWARE
*the Web
* the Web
*webUI (is a product) - use 'web interface' or 'web-based user interface' or 'GUI'
* 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'


;Good
*Proxmox Server Solutions GmbH
*Proxmox VE
*Proxmox Virtual Environment
*Proxmox Mail Gateway
*the web
*a how-to (guide)
*OpenVZ
*CentOS
*VMware
*Ceph
*Ceph Filesystem, Ceph Object Storage, Ceph Block Devices, Ceph Storage Cluster


== Gender ==
== Gender ==

Revision as of 10:26, 14 November 2023

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 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: