Conventions

You can use all of the formatting and different components that AsciiDoc allows. We do define some exceptions for better consistency when working with more flexible components. The conventions listed below must be followed when contributing to any part of the documentation.

Lists

Ordered lists: Ordered lists should be defined with the . instead of using actual numbers. For example:

. List point 1,
. list point 2.

Unordered lists: Unordered lists should be defined with the *. For example:

* List point 1,
* list point 2.

Use ordered/unordered lists only when the lines are relatively short. If the list should provide detailed description, use the multi-line description block:

// Make the general outline outline the entire content of the description.
[General outline here]::
    [Description here].

For example:

== Product overview documentation

...

Product Overview::
    Describe what the product is and what it’s not...

Security::
    Provide a rough overview over the security system - users, roles, access control and so on...

Architecture::
    Outline all of the important components and what they are and/or could be used for...

...

Code snippets

Short one-liners: When specifying short code snippets such as a CLI command use the single backtick (`),
Longer code snippets: Try to avoid long code snippets as much as possible unless when working on examples. Use the source code syntax [source,{language here}] blocked 4 dashes ----. For example:

[source,adoc]
----
----

Admonition

Use the admonition block syntax when wanting to create admonitions. For example:

[IMPORTANT]
====
This is *very* important!
====