Style Guide

General recommendations

• All files and folders should be lower case
• EGI Services should be named exactly as in the EGI Services Portfolio
• Acronyms should be used only when it makes sense
• Service names should never be replaced by acronyms
• When introducing services, link to the public page of the service, if any:

[EGI Cloud Compute](https://www.egi.eu/service/cloud-compute/)

Markdown writing guidelines

Documentation pages have to be written in Markdown, compliant with CommonMark and GitHub Flavored Markdown.

Basic rules

• Headings must start at level 2 (##), as level 1 (#) is the title of the page
• Lines should be wrapped at 80 characters
• Sentences must be separated by one space only
• Indent is made with spaces, not with tabs
• Bullet lists should be using - not *
• Numbered lists should be using 1. for each line (automatic numbering)
• Indent secondary (and following) level lists with 2 spaces
• Lines must end with a Line Feed character (\n)
• Files must end with an empty line
• Shell examples should include a prompt ($ or >) in front of commands, to make it easy to understand which is the command and which is the output
• Commands in shell examples should be broken into multiple lines of 80 characters or less, using a trailing backslash character (\) on each line that continues on the next
• Never break command output in shell examples to multiple lines, instead use style exceptions when necessary

Automating formatting and checking

Style should be enforced via the usage of Prettier. Prettier can be integrated with various editors.

• With VIM/neovim it can be used via a plugin like ALE as described in the official documentation.
• With VisualStudio Code please see the official documentation

Configuration is provided in .prettierrc, options can be set as follows:

--print-width 80 --tab-width 2 --prose-wrap always

When a contribution is received (via a pull request), the proposed changes are checked using various linters.

General writing guidelines

Follow the guidelines below to ensure readability and consistency of the EGI documentation. These are based on the OpenStack documentation writing style guidelines, released under a Creative Commons license.

Use standard English

Use standard British English (UK) throughout all technical publications. When in doubt about the spelling of a word, consult the Merriam-Webster’s Collegiate Dictionary and the IBM developerWorks editorial style guide.

Be clear and concise

Follow the principles of minimalism. If you can describe an idea in one word, do not use two words. Eliminate all redundant modifiers, such as adjectives and adverbs.

Write objectively

Do not use humor, jargon, exclamation marks, idioms, metaphors, and other colloquialisms.

Describe the most common use case first

Put the most common case in the main clause and at the beginning of a paragraph or section. You can introduce additional use cases by starting a sentence with “however” or “if”.

Write in active voice

In general, write in active voice rather than passive voice. Active voice identifies the agent of action as the subject of the verb, usually the user. Passive voice identifies the recipient (not the source) of the action as the subject of the verb.

Active-voice sentences clarify the performer of an action and are easier to understand than passive-voice sentences. Passive voice is usually less engaging and more complicated than active voice. When you use passive voice, the actions and responses of the software can be difficult to distinguish from those of the user. In addition, passive voice usually requires more words than active voice.

• Examples

However, passive voice is acceptable in the following situations:

• Using active voice sounds like you are blaming the user. For example, you can use passive voice in an error message or troubleshooting content when the active subject is the user.

• Example

• The agent of action is unknown, or you want to de-emphasize the agent of action and emphasize the object on which the action is performed.

• Example

• Recasting the sentence in active voice is wordy or awkward.

• Example

Write in second person

Users are more engaged with documentation when you use second person (that is, you address the user as “you”).

Writing in second person has the following advantages:

• Second person promotes a friendly tone by addressing users directly.
• Using second person with the imperative mood (in which the subject you is understood) and active voice helps to eliminate wordiness and confusion about who or what initiates an action, especially in procedural steps.
• Using second person also avoids the use of gender-specific, third-person pronouns such as he, she, his, and hers. If you must use third person, use the pronouns they and their, but ensure that the pronoun matches the referenced noun in number.
• Use first person plural pronouns (we, our) judiciously. These pronouns emphasize the writer or EGI rather than the user, so before you use them, consider whether second person or imperative mood is more “user-friendly.” However, use “we recommend” rather than “it is recommended” or “EGI recommends”.

Do not use first person to avoid naming the product or to avoid using passive voice. If the product is performing the action, use third person (the product as an actor). If you want to de-emphasize the agent of action and emphasize the object on which the action is performed, use passive voice.

The first-person singular pronoun “I” is acceptable in the question part of FAQs and when authors of blogs or signed articles are describing their own actions or opinions.

• Examples

Use the present simple tense

Users read documentation to perform tasks or gather information. For users, these activities take place in their present, so the present tense is appropriate in most cases. Additionally, the present tense is easier to read than the past or future tense.

• Example

Do not humanize inanimate objects

Do not give human characteristics to non-human subjects or objects.

• Example

Avoid personification

Do not express your fears or feelings in technical writing. Avoid the adverbs such as “probably”, “hopefully”, “basically”, and so on.

Avoid ambiguous titles

Each title should include a clear description of the page’s or chapter’s subject.

• Example

Eliminate needless politeness

Do not use “please” and “thank you” in technical documentation.

Write positively

Write in a positive tone. Positive sentences improve readability. Try to avoid the following words as much as possible:

• Examples

Do not use contractions

Generally, do not contract the words.

• Examples

Do not overuse this, that, these, and it

Use these pronouns sparingly. Overuse contributes to readers’ confusion. To fix the ambiguity, rephrase the sentence.

• Example

Do not split infinitives

Do not place modifiers between “to” and the verb. Typically, placing an adverb or an adjective between “to” and a verb adds ambiguity to a sentence.

Avoid prepositions at the end of sentences

As much as possible, avoid trailing prepositions in sentences by avoiding phrasal verbs.

• Example

To fix the verb-preposition constructions, replace them with active verbs.

• Examples

Use consistent terminology

Use consistent terms across all content. Avoid multiple variations or spellings to refer to the same service, function, UI element, and so on.

Use spelling and grammar checking tools

Run text through spelling and grammar checking tools, if available. Correcting mistakes, especially to larger sections of new content, helps eliminate rework later.

Lists

When reading a document for the first time, users scan through pages stopping only on the content that stands out, such as titles, lists, links, diagrams, and so on. Lists help to organize options, as well as help readers to find information easily.

When listing items, follow these guidelines:

• Use a bulleted list for options. Create a bulleted list when you need to describe more than three options.
• Use a numbered list for steps.
• Use a definition list to explain terms or describe command-line parameters, options, or arguments.
• Use a colon at the end of the sentence that introduces a list.
• Use the same grammatical structure (aka parallel structure) for all items in a list.
• Start each option with a capital letter.

When listing options in a paragraph, add and or or before the last item in a list. Use a serial (Oxford) comma before these conjunctions if they connect three or more items.

Punctuation in lists

In bulleted lists:

• If you list individual words or phrases, do not add a period at the end of each list item.
• If you use full sentences, add a period at the end of each sentence.
• If your list includes both individual words or phrases and full sentences, be consistent and either add or do not add periods to all items.

In numbered lists:

• Add periods at the end of steps.
• If an item of a numbered list is followed by a code block that illustrates how to perform the step, use a colon at the end.

Adding exceptions for style violations

Successfully passing the checks is a firm requirement, but for the following cases it is possible to add exceptions and bypass some checks in Markdown files:

• When in-line HTML must be used (e.g. in tables, or when no other proper solution is available)
• When the same procedure needs to be described for multiple platforms, and the automatic checker flags it as duplicate content

Dealing with in-line HTML tags

In some specific cases it is impossible to use anything but in-line HTML tags:

• Presentation page leveraging bootstrap CSS classes or other advanced features
• Using special formatting for the information presented (e.g. a list in a table cell)

Blocks with in-line HTML tags should be preceded by a HTML comment starting with markdownlint-disable to disable the no-inline-html check, as in the following example:

<!-- markdownlint-disable no-inline-html -->

| Action      | OCCI                     | OpenStack              | This is a very long column with important data |
| ----------- | ------------------------ | ---------------------- | ---------------------------------------------- |
| List images | `occi -a list -r os_tpl` | `openstack image list` | <ul><li>Lorem</li><li>ipsum</li></ul>          |

<!-- markdownlint-enable no-inline-html -->

Dealing with duplicate content

When the same procedure needs to be described for multiple platforms, or when the same code has to be exemplified for multiple languages, it is possible that the automatic checkers will flag these as duplicates.

For example, describing the following procedure will result in duplicates being reported:

{{< tabpanex >}}

{{< tabx header="Linux" >}}
  To run the FedCloud client in a container, make sure
  [Docker is installed](https://docs.docker.com/engine/install/#server),
  then run the following commands:

    ```shell
    $ docker pull tdviet/fedcloudclient
    $ docker run -it tdviet/fedcloudclient bash
    ```
{{< /tabx >}}

{{< tabx header="Mac" >}}
  To run the FedCloud client in a container, make sure
  [Docker is installed](https://docs.docker.com/desktop/mac/install/),
  then run the following commands:

    ```shell
    $ docker pull tdviet/fedcloudclient
    $ docker run -it tdviet/fedcloudclient bash
    ```
{{< /tabx >}}

{{< tabx header="Windows" >}}
  To run the FedCloud client in a container, make sure
  [Docker is installed](https://docs.docker.com/desktop/windows/install/),
  then run the following commands:

    ```shell
    > docker pull tdviet/fedcloudclient
    > docker run -it tdviet/fedcloudclient bash
    ```
{{< /tabx >}}

{{< /tabpanex >}}

This type of content should be preceded by a HTML comment that disables the check for duplicates, and followed by another HTML comment that enables it again.

<!--
// jscpd:ignore-start
-->

...content with duplicates here...

<!--
// jscpd:ignore-end
-->