Skip to main content

Language Mechanics

Language mechanics govern the written English. Together with formatting guidelines, they let us present our articles in the same way across the whole wiki — meaning that the reader can focus on the matter, not the form.

Spelling

Only use the American English spelling.

Glossary

Whenever you use a technical term, check the IOTA glossary for the accepted notation.

Whenever you encounter a term that is written in different ways across documentation, please propose a unified spelling and make a designated pull request that adds a new entry to the glossary and ideally replaces all occurrences of improper spelling in the wiki. This will help both writers and readers.

Names

Always write a personal or brand name in its owner's preferred spelling:

Good:

Aleksei

Johnson & Johnson

Bad:

Alexey

Johnson and Johnson

This case overrides other guidelines.

IOTA Products

Refer to IOTA libraries by their filenames: idenity.rs, iota.go, etc. Always use the lower-case notation. Note that it is harder to spot a sentence if it starts in lower case. Consider using the following clause instead: "The identity.rs library".

Other IOTA products have an actual name. Always capitalize it: "A Hornet node. Hornet and Identity."

Note that there are no determiners (the) when you refer to something by its name: "the identity.rs library" as in "the library named identity.rs", but simply "identity.rs".

Good:

The identity.rs library connects to a node. A node could be a Hornet node, but identity.rs handles both the same way.

This case overrides other guidelines.

Punctuation

Use the American English punctuation.

Use serial commas:

Lock, stock, and barrel.

Reserve exclamation marks only for special occasions.

Typography

Type em-dash ("—") and ellipsis ("…") with the designated symbols, not as a single or double en-dash ("-", "--") or a triple dot ("..."):

Somehow this invaluable tool is widely regarded as not quite proper — a bumpkin at the genteel dinner table of good English.

On Writing Well by William Zinsser

Quotes

Never modify quotes. Fix typos in a quote only if you are the first to publish it. This paragraph overrides other guidelines.

Do not contract short quotes. Put […] in place of an omitted part. Never omit parts that change the meaning of the quote, its emotion, or anything else that could lead to misinterpreting it.

Use American English style notation: use double ticks (") and put commas and full stops inside the quote. For long quotes, use paragraph-style quotes instead.

Date and Time

Use DD/MM/YYYY format for dates and 24h clock for time: HH:MM or HH:MM:SS. Do not use this time format for time spans as measurement units would not be clear: instead say "2 hours, 10 minutes, 6 seconds" or "2h 10m 6s". Use plain English for approximate gauges: "This calculation takes less than ten minutes."

Measurements

Use the International System of Units and associated symbols and prefixes (5 kg, 3.25 m, 500 TiB).

Numbers

Use the dot for decimal values (1.25, 0.025). If you need to split a large number to make it easier to understand, use spaces instead of commas to avoid confusion: "2 824 683 000 IOTA tokens".

A spelled out integer is often easier to read: "eleven nodes", "one million ticks". This is usually the case for any round number and for any number that is less than a hundred.

Abbreviations, Emojis, and Contractions

Everyone uses abbreviations, emojis, or contractions in informal writing or chat. They help to keep up with a live discussion, as we can type less and be less scrupulous with the choice of words, as we can always add a smiley face to make our emotion clear.

Avoid using it in the documentation, as these mechanics have their drawbacks. Abbreviations require extra effort to decipher the text, contractions are sometimes ambiguous ("would", "could", "should", "had"), and bright, colorful emojis break the reading flow as they distract the reader from the body of text. If your prompt sounds too formal or aggressive, rewrite it altogether.

Abbreviations

Avoid contracting a word or replacing it or its parts with a numeronym or special symbol:

Good:

Lock, stock, and barrel

Good night, sweet prince

Little John

Bad:

Lock, stock & barrel

Good n8, sweet prince

Li'l John

Use acronyms sparingly. Always provide the full name the first time you mention something in an article:

Distributed Ledger Technology (DLT) makes decentralized digital databases secure. Most DLTs use blockchains.

Remind the reader what does the acronym mean if you have not mentioned it in the previous few paragraphs.

Contractions

Never use contractions:

Good:

I would rather use contractions.

Bad:

I'd rather use contractions.

Also see Negations for "don't"s.

Emojis

Never use Emojis:

Good:

Go to the designated evacuation point.

Bad:

Go 🏃‍♂️ 🔥 to the designated evacuation point.