Documentation

Contribution Rules

Below is a list of rules that apply to every contributor of any Corteza repository. With the below points, we wish to provide consistent, quality software that is easy to use and get involved with.

Document your major modifications

A modification classifies as major when it changes the features output, or the concept of the logic differs from the prior version. For example:

changed api response;
change in the access control logic;
additional settings, environment variables;
changed the interface for data export; and
new features.

All relevant guides must be updated

When a modification affects multiple guides, each of them needs to be taken care of (see the Structure Overview section for more details). If the change is not backwards compatible, make sure to take note in the upgrade guide. For example, your feature introduces a new application with a new API and a user interface. You should update the:

developer guide;
administrator guide; and the
end-user guide.

Consistent style of writing

Be consistent with other contributors as we wish to have a consistent, easy to read documentation. Refer to the writing guidelines for more insight on this.

Try to follow the rules

In an edge case where you are not able to work on the documentation straight away, open a new issue that outlines the changes and provides some references. No big deal, as long as it gets done before the release.

If you refuse to follow the above guidelines for any reason, you will not be able to contribute to the project.

We all hate it when a fantastic framework or platform lacks in the documentation, and we have to reverse engineer every little feature. How good is a product if no one knows how to use or maintain it? Let’s not make our lives harder by not wanting to share our knowledge!

Stuck? Get in touch with us on https://latest.cortezaproject.org!

Conventions

Use the following conventions as a reference when you wish to do some extra formatting to your documents.

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

Please follow the below conventions when contributing to the documentation.

Composition

When composing documents that will be consumed from a device, it is essential to define a stable, easy to understand, and compact structure. Here are a few tips to help you out:

Visually group things: Use paragraphs, lists, admonition blocks, and other blocks to visually group things that fit together. If something is not relevant in this section but is appropriate in the next one, move it there.
Use formatting to break monotone text: Use bold, italic, links, inline code blocks, and other formatting to expose the crucial bits for that paragraph. Do not go overboard.

Lists

Use lists to give the document some additional structure, outline the * essential bits*, or show a sequence of things.

General rules:

Try to keep them as short as possible, as they can make it harder to read.
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.
Do not mix proper sentences and non-proper sentences.

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.

Example of a not-proper sentence; you should know how to use:

Golang,
JavaScript,
VueJS.

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). For example:

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

Unordered lists

List items in an unordered list should start with a star (* …content here…). For example:

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

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.

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

For example:

== 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 are getting long and feel like they should be in a new sub-section — do that instead.

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 ----. For example:

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

Admonition

Use the admonition block syntax when wanting to create admonitions; where you want extra attention. For example:

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

You can use; they are self-explanatory:

NOTE
TIP
IMPORTANT
WARNING
CAUTION

Diagrams

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

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

.Provide a good caption to summarize the *entire* diagram. You can't multi-line captions, so we'll allow it like this here.
[plantuml,diagram-name-here,svg,role=diagram-name]
----
@startuml

' Diagram definition goes here

@enduml
----

Larger diagrams can get a bit messy to understand what is going on, so 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 know what’s going on in the diagram. Make sure that the caption gives the reader enough insight to have an idea what they can expect to learn from the diagram.

We are quite strict in having 1 sentence per line to have nicer version history. Here, however, I am unable to figure out how/if this is possible. You are free to inline your captions (for now).

Comments: A PlantUML comment starts with ' (single line), or is enclosed between /', and '/. We’ll use the following notation to be consistent:

' ---------------
' 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:ROOT:guide-goes-here/path-to-source.adoc[label-goes-here]

// For example:
xref:ROOT:end-user-guide/messaging/index.adoc[{PRODUCT_NAME} {APP_NAME_MESSAGING}]

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. If you try to link to something that is not on the screen, the link will not work. Use page cross-references.
Keep section ID’s simple: Section ID’s are relevant only for the given page. They don’t need to be unique across the entire documentation, just for the current page. Example: [#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’ll outline the base guidelines that you need to follow when contributing to the documentation.

You can refer to this article or any other article for additional insight.

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 which is always a plus!

There are some exceptions when you should not use the active voice:

When we are talking about errors it would sound like we are blaming the user!
If it makes the sentence much longer.

Use the present simple tense

Users refer to the documentation to find out how they can do something. Let’s give them the feeling like *we are walking them through this process. It also makes it shorter and a bit * more comfortable to read* then with other tenses.

When you are describing things where present simple tense doesn’t make sense, you are free to use the appropriate tense.

Use second person

This makes it sound more engaging as it involves more people than just you and I.

For example:

I have defined this feature that can be used to …

sounds nicer if we reword it to:

We have defined this feature that you can use to …

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

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 I didn’t force you to read through them. The next sentence is the only thing that I wanted to state in this sub-section, so I’ve successfully wasted some of your time :). Let’s get straight to the point and tell our readers exactly what they want to know without wasting their time.

Let’s get straight to the point and tell our 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 when we think we’ve found what we are looking for.

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 essential bits.

Things that make sense together should stay together, something that do not, should not.

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 go over the top with images by showing every single step of the way or even worse by just pasting a screenshot with no context what we are looking at.

When including images make sure to indicate what the image represents and make sure to provide an image caption that outlines what is going on in the image. It also allows our readers to quickly refresh their memory if they are already familiar with something.

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

Use syntax checkers (and semantics checkers)

Tupos happen. There are a lot of great free tools, as well as some paid ones.

User Roles

DevOps

A DevOps is someone responsible for deploying and maintaining the Corteza instance. They need to now things like how to configure the docker-compose, what configurations are available, and what services need to run on the server.

End-User

An end-user is someone who is not necessarily a field-expert and needs to know how to do something. They need to do things like how to create a new record, how to log in, and how to send a formatted message.

Don’t consider them field experts, and use simple word with as little complex terminology as possible.

Administrator

An administrator is someone responsible for setting up and maintaining security-related parts of the system, such as user roles, users, and permissions.

These users should be knowledgeable in these fields to perform the tasks effectively.

Integrator

An integrator is someone responsible to create an integration for either themselves or a client. An integration extends on the base Corteza features. These users should be field experts on designing such systems.

Developer

A developer is someone who is responsible (or would like to contribute) for the core Corteza repositories. These users should be field experts on the subject.

Structure Overview

A few notes before we get into the fun bits:

There is no "cookie-cutter" solution: When it comes to such systems, there are multiple different types of users involved. From the end-users who usually aren’t techy people, to administrators that worry about the system’s integrity, to developers that maintain existing features and implement new features. That is why there can’t be a "one fits all" kind of solutions.
Tell me everything!!: Let’s not make our readers jump from one doc to another just because it’s easier that way or it shortens the thing. As a reader of the "Integrator Guide" I want to have all the relevant information without the need reading up on another one.
Copy-paste is ok (sometimes): If different roles are interested in the same thing, for example, module field types, let’s not make them jump to another documentation just to read up on that and get lost in the process. Let’s have it in both places. If we are smart about it, we can define smaller snippets that can be included in both parts.

Onto the fun stuff!

Homepage

The homepage should provide a high-level overview of the entire thing. Quickly outline what Corteza is and reference all of the different documentation and relevant resources.

You can also provide some references to subsections within specific documents to get the reader to where they want to be faster.

Consider your reader as a non-techy end-user, so use simple terminology until they get to the guide they are interested in.

DevOps guide

Provide a fairly high-level overview over all parts that a DevOps person cares about — from deploying to maintaining.

Here, we don’t define a strict structure, so you are allowed to structure as you see fit.

End-User Guide

Provide a high-level overview over all features from the end-user perspective.

It should be as short and condensed as possible, as the end-user doesn’t care of all the technical details such as what protocols and frameworks we use. All they wish to know is

How do I achieve this while using Corteza?!

For consistency we define the following structure:

= {APPLICATION_NAME}

// Provide a quick TL;DR of the application.
// What is the purpose; who can use it

== {APPLICATION_FEATURE_NAME}

// Describe the feature as abstractly as possible while giving the end-user the confidence to use this feature.
//
// Here, we should combine multiple smaller features into one (make sure they are related).
// This allows us to create shorter documentation that is much friendlier to the end-user.
// For example, instead of creating multiple sections for Sending messages, Editing messages, and Deleting messages; we can define a single Messages section that gives the user enough knowledge to work with messages.
//
// Then to give them more insight into mentioning users and text formatting (the complicated bits), we define new sections Formatting text and Tagging users that focus solely on that.

Here, we should also cover:

Getting Started: Cover the first steps that the user should take. For example, how to register, how to log in, how to change their username/email, and so on.

Administrator Guide

Provide a relatively high-level overview from the system administrators perspective.

Provide an overview of the configuration, administration and management of the system; such as defining permissions, managing users, and managing roles.

The section should define multiple subsections where each describes an application that Corteza defines; such as Corteza Messaging. For consistency we define the following structure:

= {APPLICATION_NAME}

// Provide a quick TL;DR of the application.

== {APPLICATION_FEATURE_NAME}

// Describe the feature to the extent where an administrator will be confident with using it.
// Keep it as short as possible but do provide all the important details!
//
// Here, we should cover multiple smaller features into one (just make sure they are related).
// This allows us to create shorter documentation that is much friendlier to the administrator.
//
// For example, instead of creating multiple sections for Creating users, Deleting users, and Editing users; we can define a single Users section that gives the user enough knowledge to perform any user-related operation.
// Then to give them more insight into managing roles, we define a new section Membership that focuses solely on that.

Here, we should also cover:

Security: Describe in detail how the security system works - users, roles, access control, permissions and permission states (allow, deny and inherit). Aggregate all the available permissions for each system.

Integrator Guide

Provide a detailed overview of the entire integration process. The document should be written for field experts, so we needn’t worry about their limited knowledge on the subject.

It should provide enough insight into the system, terminology and other bits such as extension development so that the reader can extend the base Corteza for either themselves or a client.

We should define multiple sections where each section focuses on a specific aspect of the integration. From configuring Low Code, to deploying extensions. Each section should solely focus on its context.

Make sure to keep the content somewhat abstract, but provide enough low-level knowledge so the integrator knows what something does.

Here, we should also cover:

Security: Describe in detail how the security system works - users, roles, access control, permissions and permission states (allow, deny and inherit). Aggregate all the available permissions for each system.
Tips and Tricks: Hack down some findings and good practices discovered from past projects, such as creating a portal for end-users.

Developer Guide

Provide a low-level overview over the entire system and all the available features.

It should focus on how a feature functions, what parts (endpoints, services, …) of the system are included to provide a general idea of the internal logic. It should not focus on implementation details (what functions are called and their arguments, what libraries are used) as it is visible from the source code.

The section should describe multiple subsections where each describes an application that Corteza defines; such as Corteza Messaging. For consistency we define the following structure:

= {APPLICATION_NAME}

// Provide a quick TL;DR of the application.

== {APPLICATION_FEATURE_NAME}

// Describe the feature to the extent where a maintainer understands what parts of the system are involved when working on this feature (improvements, bugfixes, ...).
//
// Here, we should cover multiple smaller features into one (just make sure they are related).
// This allows us to create shorter documentation that is much friendlier to the reader.
//
// For example, instead of creating multiple sections for Creating users, Deleting users, and Editing users; we can define a single Users section that gives the reader enough knowledge to understand what parts are involved.

Here, we should also cover:

Documentation: Well… this is it. If you’re reading this, then hi! Describe the different documentations, provide some guidelines and describe the process of contributing documentation.

Upgrade Guide

Provide a step-by-step guide on the steps you need to take to upgrade to a newer version of Corteza.

Each version should be in its section, with free structure underneath. The latest version should be presented on the top, with the past versions under the Archive.

Extensions

The purpose is to provide an overview of all available extensions from the integrators perspective.

Each extension should define its section where it is described in detail. For consistency we define the following structure:

= {EXTENSION_NAME}

// Provide a quick TL;DR of the extension.
// Split this subsection further as you see fit.

If you are developing your extensions, provide your documentation and don’t merge it here unless we agree on making it an official extension.

Examples

Getting Started

Sample Feature

For an easier representation, we use the following feature specification:

The sample feature implements a brand new monitoring system for all devices connected to the core system; their availability and memory consumption. The feature defines a new API, a new database schema and a modern web app.

The web app implements a pulling system, that periodically fetches the system information, sends it over the API and stores it in the database. Besides storage, the API also allows fetching, updating and deleting the data.

Take note of the important bits

Specify a set of bullets (sections) that outline the important parts of the system — the things you want the readers to remember.

For example:

* security
* front-end
* backend
* repository

Expend on the main things

Expand the main sections. Break them down into the main components that outline the section.

For example:

* security
** available permissions
** the scope of each permission
** guidelines

* front-end
** important libraries used
** browser compatibility
** used algorithms
** communication with the backend

* backend
** access control
** used algorithms
** limitations such as throttling

* repository
** tables, fields and their types

Iterate over your bullets

Iterate over your documents and progressively expand and refactor your content. Try to rewrite the same paragraph multiple times to see what fits best. Add some admonition blocks and text formatting.

For example:

= Monitor

This feature implements a system that monitors the clients connected to the {PRODUCT_NAME} Monitor core system.

== Security

== Available permissions

Monitor log::
    The permission allows the role to create a log entry for the Monitor system.
    We should only grant this permission to the users that we want to know about,

Monitor list::
    The permission allows the role to access the stored Monitor data.
    Such users can analyse the data to create reports,

Monitor log delete::
    The permission allows the role to remove a log entry from the monitor system.
    Be careful with this one, as we don't want users to remove information needlessly.

...

The above is just an example and an outline of how I get about doing documentation. I find that this helps me define a better, more structured document as I go over the entire thing multiple times.

Removing Jank

For an easier representation, we use the following feature specification:

Lets now imagine the following documentation:

= Monitor

This section describes the {PRODUCT_NAME} Monitor feature.
The {PRODUCT_NAME} Monitor feature monitors the clients connected to the core {PRODUCT_NAME} system.

== Security

The security is one of the most critical areas that need to be addressed, as it allows us to restrict access to sensitive information.
The system checks if we can access a specific resource based on our user roles (RBAC).
The rest of the subsection outlines available permissions, their context and provides some guidelines and some notes.

Monitor log::
    The permission allows the role to create a log entry for the Monitor system.
    We should only grant this permission to the users that we want to know about,

Monitor list::
    The permission allows the role to access the stored Monitor data.
    Such users can analyse the data to create reports,

Monitor log delete::
    The permission allows the role to remove a log entry from the monitor system.
    Be careful with this one, as we don't want users to remove information needlessly.

Now, let’s analyse and clean it up a bit.

This section describes the {PRODUCT_NAME} Monitor feature.

Yes, we know, since we can read the title of the section.

The security is one of the most critical areas that need to be addressed, as it allows us to restrict access to sensitive information.
The system checks if we can access a specific resource based on our user roles (RBAC).

We are just stalling and repeating the same thing that should be outlined in the security chapters. Sometimes it is a good idea to repeat important bits of information, but not here as it should be self intuitive from the sub-sections title.

The rest of the subsection outlines available permissions, their context and provides some guidelines and some notes.

Again; we’re just stalling and padding for longer content.

If we wish to provide an outline of the important sections, let’s just define a new section so it’s visible from the navigation/table of content.

If we take into consideration the above analysis, we can condense the documentation down to the following:

= Monitor

This feature implements a system that monitors the clients connected to the {PRODUCT_NAME} Monitor core system.
Reports statistics.

== Security

=== Available permissions

Monitor log::
    The permission allows the role to create a log entry for the Monitor system.
    We should only grant this permission to the users that we want to know about,

Monitor list::
    The permission allows the role to access the stored Monitor data.
    Such users can analyse the data to create reports,

Monitor log delete::
    The permission allows the role to remove a log entry from the monitor system.
    Be careful with this one, as we don't want users to remove information needlessly.

We can see that the content is a bit shorter and straight to the point. We don’t want to waste the readers time with needless content, so let’s just keep it short and straightforward.

Documentation

Contribution Rules

Conventions

Composition

Lists

Ordered lists

Unordered lists

Multi-line description blocks

Code snippets

Short one-liners

Longer code snippets

Admonition

Diagrams

Referencing

Important notes

Writing Guidelines

Use active voice

Use the present simple tense

Use second person

Follow the KISS principle!

Keep things structured

Use admonition

Use images…​ sparingly

Use syntax checkers (and semantics checkers)

User Roles

DevOps

End-User

Administrator

Integrator

Developer

Structure Overview

Homepage

DevOps guide

End-User Guide

Administrator Guide

Integrator Guide

Developer Guide

Upgrade Guide

Extensions

Examples

Getting Started

Sample Feature

Take note of the important bits

Expend on the main things

Iterate over your bullets

Removing Jank

Use images… sparingly