Conventions

When writing, please use the following conventions as a reference, especially for when you wish to add some extra formatting to your documents.

The bellow list is aggregated from AsciiDoc, shortened and adjusted to our needs.

Please, do your best to follow the conventions listed below when contributing to the documentation.

We are quite strict in having 1 sentence per line to have a nicer version history of the document in production.

Composition, formation, layout

When composing any text it is important to pay attention its formation and layout, especially so when we talk about documents viewed via electronic devices.

It is essential to produce a document that is easy to understand and stable from both the perspective of contents and the visual perspective. Consistency is crucial.

It may be good to:

Visually group

Make sure you group components that fit together, i.e., discussions of the same concept, concept and an example, subpoints and tips…

If something is not relevant in a section, move it elsewhere. It is better to add a section than to compromise on coherency and fluidity of the document.

Drawing attention to crucial points

Use bold, italic, links, inline code blocks, and other formatting to point out crucial points you make.
Do not go overboard, as highlighting excessively results in the decrease of attentitivenes to a highlighted sections.

Lists

You can use lists to provide the document with additional structure, to outline the essential points, display a sequence etc. Try to keep lists short, as they can make the document harder to read.

Punctuation:

If a list item is a proper sentence, start with a capital letter, and end with a period.
If a list item is not a proper sentence, start with a lowercase letter, and (optionally) end with a comma. In case you choose to use commas, start the first item with a capital letter end the last one with a period.
If the entire list is one sentece broken down into clauses for each point, make sure to start the first list item with a capital letter, finish up the point with a comma, continue with a lowercase letter in the following point, finish it up with a comma and so on. Wrap the list up with a period.
Do not mix sentence patterns when producing a list.

Example of a proper sentence; the outline of our documents:

The end-user guide talks about things relevant to the end-users.
The integrator guide talks about creating new things based on the Corteza.
The developer guide helps the core developers keep track on how to maintain different features.

Ordered lists

List items in an ordered list should start with a dot (. …content here…) instead of an actual number (it gets assigned at compile-time). Please, see the below example.

.Here we can see:
. list item 1,
. list item 2.

Multiple dots should be used when you are indenting the line item. Please, see the below example.

. item (this becomes 1.)
.. sub item (this becomes a.)
... sub sub item (this becomes i.)

Unordered lists

List items in an unordered list should start with a star (* …content here…). Please, see the below example.

.Here we can see:
* list item 1,
* list item 2.

Multiple asterisks (* symbol) should be used when indenting the line item.

If your list items are long, try to restructure your section, or use multi-line description blocks.

Multi-line description blocks

Use description blocks when your lists start getting long. They firstly present the key point of the block, followed by a more detailed description that is shifted to the right.

// Make the key point outline the full description.
// Use four spaces to indent the description.
[Key point here]::
    [Description here].

To examplify:

== Corteza documentation structure

DevOps guide::
    The DevOps guide covers all of the DevOps related bits, such as deploying and maintaining.
    ...

End-user guide::
    The end-user guide serves as a reference for end-users that need help with using the Corteza's user interface.
    ...

Integrator guide::
    The integrator guide serves as a reference for integrators -- people that want to build things with Corteza.
    ...

Try not to overuse this. If your descriptions get long, it may be better to restructure and divide the text into several sub-sections instead.

Including code snippets

Short one-liners

Use short one-liners when you wish to show specific things inline, such as CLI commands, object properties, and variables.

Longer code snippets

When working on examples or longer code snippets, use the source code syntax; [source,{language here}]; blocked with four dashes ----. Please, see the below example.

[source,adoc]
----
// Things go here
----

Admonition

Use the admonition block syntax when wanting to create admonitions; where you want extra attention to be drawn to.

You can use the following:

NOTE
TIP
IMPORTANT
WARNING
CAUTION

These are pretty much self-explanatory. Do not overuse.

Diagrams

Use the PlantUML framework for any diagrams (unless there is an explicit reason for not doing so). This allows us to keep things consistent, preserve version history and easy to maintain.

Move larger diagrams into separate files to avoid clutter and unreadable source.

Provide a good caption to summarize the entire diagram. You shouldn’t use more than one line for a diagram caption.

[plantuml,diagram-name-here,svg,role=diagram-name]
----
@startuml

' Diagram definition goes here

@enduml
----

Larger diagrams may be harder to understand. Do your best to group elements together, and use a nice comment to indicate it.

Diagram captions: A caption must be enough for the reader to get an idea about what goes on in a diagram. Make sure that the caption gives the reader enough insight to have an idea what they can expect to learn from the diagram.
Comments: A PlantUML comment starts with ' (single line), or is enclosed between /', and '/. Please, use the following notation for the sake of consistency;

' ---------------
' Define comments like so.
' Multiple lines are fine.
' ---------------

Diagram structure: You are free to use any diagram and any component defined by the diagram. Avoid visual customization using Skinparam.

Referencing

Use referencing to link different bits of information. We use two different types of references:

Page cross-references: Page cross-references allow us to link between different documentations, or even different versions. Use the xref macro (The Antora documentation):

// Template
xref:guide-goes-here:path-to-source.adoc[label-goes-here]

// For example:
xref:integrator-guide:workflows/index.adoc[Workflows]

You can also use anchors in your `xref`s.

Same page references: Same page references allow us to link in the same documentation section. use the simple page ID reference syntax (The Antora documentation):

// Define a section ID (make sure that it starts with a #)
[#id-goes-here]

// Reference the section ID (there is no # here)
<<id-goes-here>>

// Reference the section ID with a custom label (no space after the comma)
<<id-goes-here,custom-label-goes-here>>

Important notes

Same page references are simple: Same page references can only link to things that are on the current page. In case you try to link to something that is not on the screen, the link will not work. Use page cross-references.
Keep section IDs simple: Section IDs are relevant only for the given page. They don’t need to be unique across the entire documentation, just for the current page. To examplify; [#extension-deployment]
Don’t go overboard: If somesomething is required for the understanding of the given section, add a quick summary and link to the complete document afterwards.