Documentation

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.

Writing Guidelines

Here, we outline the base guidelines that you should to follow when contributing to the documentation.

Use active voice

Active voice identifies the subject that has performed the given action; for example:

To configure external login providers go into the administration panel, authentication and configure …

This style makes the reader more involved and therefore makes it friendlier and more comfortable to read. It also makes it a bit shorter.

There are some exceptions to using the active voice.

Use the passive voice:

When you talk about errors; the active voice can suggest blaming the user.
When it shortenes the message.
When the subject isn’t and doesn’t need to be recognised. This includes sentences in which you wish to identify the first person.
- This often overlaps with the use of tense.

To examplify observe the difference in tone the below sentences;

I/we have defined this feature that can be used to …

This feature is defined in a way that allows you to …

These points are guidelines, not rules. Make sure the text also flows, is consistent and makes sense.

Use the present simple tense

Users refer to the documentation to find out how they can achieve the desired. The present simple tense ensures the feeling of walking the user through this process. It also makes the text shorter, more understandable and more comfortable to read than any other tense does.

When describing things where the present simple does not make sense, you are free to use the appropriate tense.

Use the second person pronouns

This makes documents sound more engaging as it involves the user directly.

The use of the second person also removes gender specifics, and credits other contributors (most of the time, multiple people worked on the same thing).

Additionally, it removes you, the creator, from the text, which is something you should be going for.

Articles are a great substitute for personal pronouns.

Keep in mind who you are writing for

Even before you sit down and start writing, make sure you are aware of your audience. Does the average person from your target audience know what you are talking about?

If you are unsure, either provide a brief explanation of the concept you are talking about or direct the reader to previous documents. It is better to repeat then to have your readers confused.

Another thing to keep in mind is that you are not writing for a friend; make sure the reflects that. Avoid using stylistically marked expressions, emojis, etc.

Follow the KISS principle!

How many times have we given up on reading documentation because it was all just filler text to produce more and more pages? I bet you wouldn’t read these introductory paragraphs if you weren’t forced to read through them. The next sentence is the only thing that I wanted to state in this sub-section, so some of your time has successfully been wasted :) (Oh, look, the present simple tense isn’t used here - as it would make no sense. The point? Know why you are doing what you are.).

Get straight to the point and tell the readers exactly what they want to know without wasting their time.

Keep things structured

When reading, people usually skim through the content or stop altogether what they are looking for has been found.

If we don’t do any separation between different parts it all becomes one big blob of text. If we split things too much our readers might miss any essential bits.

Things that make sense together should stay together, something that does not make sense together should not stand together.

A great example of a poorly structured text is the paragraph in the 'Follow the KISS principle' section; no separation, mixing topics… Strive to produce a straightforward text the is easy to navigate and logically continuous.

Use admonition

When we want our reader to pay extra attention to something or when we want to provide some helpful tips, don’t hesitate to use admonition blocks.

The reader is more likely to pay extra attention to something important if it is in a lovely red box with the word "Important" next to it.

Use images. Sparingly.

Don’t provide excessive visual material by showing every single step of a process or, even worse, by just pasting a screenshot with no context of what we are looking at.

When including images, make sure to indicate what the image represents and to provide an image caption that outlines what goes on in the image. An image may allow the reader to quickly refresh their memory if they are already familiar with something.

Keep in mind that UI changes will require these images to be updated.

Use syntax checkers (and semantics checkers)

Typos happen. There are a lot of great free tools, as well as some paid ones, that provide you with various types of suggestions for change and greater grammaticality of the text in production.