Language and style
People usually read technical documentation because they want something up and running quickly. Write simpler, more concise sentences.
Split the content into smaller paragraphs to improve readability.
This will also eliminate the need for using |br| and help us translate content faster.
Any paragraph over 6 sentences is large.
Consider your audience’s level. A getting started guide should be written in simpler terms than an advanced internals description.
If you choose to use metaphors to clarify a concept, make sure they are relatable for an international audience of IT professionals.
Only use the pronoun “we” in entry-level texts like getting started guides. In other cases, avoid using “we”, because it is unclear who that is exactly. Consider how Gentoo does it.
Use measurable facts instead of personal judgments. Different users may have different ideas of what “often”, “slow”, or “small” means.
Bad example: This parameter is rarely updated.
Good example: This parameter is updated every two hours or more rarely.
Temporal adverbs like “today”, “currently”, “now”, “in the future”, etc. are relative – that is, they are based on the time the documentation is created.
Instead of these words, use absolute terms like version numbers or years. The meaning of those terms doesn’t change over time.
If technical documentation is tied semantically to the time it was created, it increases the risk of the documentation becoming obsolete.
Bad example: Previously, the functionality worked differently. Currently, it supports SSL.
Good example: Before version x.y.z, the functionality worked differently. Since version x.y.z, it supports SSL.
Say exactly one thing in a sentence. If you want to define or clarify something, do it in a separate sentence. Simple sentences are easier to read, understand and translate.
| Don’t | Do |
|---|---|
| Dogs (I have three of them) are my favorite animals. Their names are Ace, Bingo and Charm; Charm is the youngest one. | Dogs are my favorite animals. I have three of them. Their names are Ace, Bingo and Charm. Charm is the youngest one. |
| memtx (the in-memory storage engine) is the default and was the first to arrive. | memtx is an in-memory storage engine. It is the default and was the first to arrive. |
| The replica set from where the bucket is being migrated is called the source; the target replica set where the bucket is being migrated to is called the destination. | The replica set from where the bucket is being migrated is called the source. The target replica set where the bucket is being migrated to is called the destination. |
It’s best if examples immediately follow the concept they illustrate. The readers wouldn’t want to look for the examples in a different part of the article.
When you provide a link, clearly specify where it leads. In this way, you will not mislead the reader.
Bad example:
Good example:
For more details, refer to the documentation on making links.
Use full link names.
Lists and tables help split heavy content into manageable chunks.
To make tables maintainable and easy to translate,
use the list-table directive, as described in the Tarantool
table markup reference.
Translators find it hard to work with content “drawn” with ASCII characters, because it requires adjusting the number of spaces and manually counting characters.
Bad example:
Good example:
Format large code fragments using the code-block directive, indicating the language.
For shorter code snippets, make sure that only code goes in the backticks.
Non-code shouldn’t be formatted as code, because this confuses users (and translators, too).
Check our guidelines on
writing about code.
For more about formatting, check out the Tarantool markup reference.
We say “instance” rather than “server” to refer to a Tarantool
server instance. This keeps the manual terminology consistent with names like
/etc/tarantool/instances.enabled in the Tarantool environment.
Wrong usage: “Replication allows multiple Tarantool servers to work with copies of the same database.”
Correct usage: “Replication allows multiple Tarantool instances to work with copies of the same database.”
Don’t use the following contractions:
- “i.e.”—from the Latin “id est”. Use “that is” or “which means” instead.
- “e.g.”—from the Latin “exempli gratia”. Use “for example” or “such as” instead.
Many people, especially non-native English speakers, aren’t familiar with the “i.e.” and “e.g.” contractions or don’t know the difference between them. For this reason, it’s best to avoid using them.
The word “Tarantool” is capitalized because it’s a product name. The only context where it can start with a lowercase “t” is code. Learn more about code formatting in Tarantool documentation.
Consider checking spelling, grammar, and punctuation with special tools like LanguageTool or Grammarly.
Special symbols like dashes, quotation marks, and apostrophes look the same across all Tarantool documentation in a single language. This is because the documentation builder renders specific character sequences in the source into correct typographic characters.
Tarantool documentarians are recommended to use the en dash (–) only.
Type two hyphens to insert it: --. Add spaces on both sides of the dash.
Don’t use a single hyphen as a dash.
Use the dash for the following purposes:
- To separate extra information.
- To mark a break in a sentence.
- To mark ranges like 4–16 GB (don’t surround the dash with spaces in this case).
When indicating a range like code element 1–code element 2, escape the series of hyphens using
character-level inline markup.
Otherwise, the RST interpreter will perceive the dash as part of the RST syntax:
``box.begin()``\--``box.commit()``
The following recommendations are for the English language only. You can find similar guidelines for the Russian language in the external reference for Russian proofreaders.
There are two kinds of lists:
- Where each item forms a complete sentence.
- Where each item is a phrase of three or less words or a term.
In the former case, start each item with a capital letter and end with a period. In the latter case, start it with a lowercase letter and add no ending punctuation (no period, no comma, no semicolon).
A list should be formatted uniformly: choose the first or second rule for all items in a list.
The above rules are adapted from the Microsoft style guide.
The sentence preceding a list can end either with a semicolon or a period.
Don’t add redundant conjunctions like “and”/”or” before the last list item.
General English punctuation rules still apply for text in lists.
For the text in cells, use periods or other end punctuation only if the cells contain complete sentences or a mixture of fragments and sentences. (This is also a Microsoft guideline for the English language.)
Besides, make sure that your table punctuation is consistent – either all similar list/table items end with a period or they all don’t. In the example below, all items in the second column don’t have ending punctuation. Meanwhile, all items in the fourth column end with a period, because they are a mix of fragments and sentences:
To learn more about table formatting, check the table markup reference.