Documentation
Contribution Rules
Below is a list of rules that apply to every contributor of any Corteza repository. With the below points we are able to provide consistent, quality software that is easy to use or contribute to.
- All major modifications must be documented
-
A modification classifies as major when it causes any changes to an actions output or how the action is performed. For example:
-
Changed api response,
-
change in the access control logic,
-
additional settings, environment variables,
-
changed the interface for data export,
-
new features; etc.
-
- All relevant guides must me updated
-
When a modification affects multiple guides, each of them needs to be taken care of. For example, your feature introduces a new application with a special API and a user interface. You should update:
-
Developer guide,
-
administrator guide,
-
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 Writing Guidelines for more insight on this.
- Try to follow the rules
-
In the edge case where it is excusable for you to not follow the above rules (extremely tight schedule, urgent fixes that need to be released asap, …) open up an issue that outlines your changes, provides some references to the PR/commit so someone (preferably yourself) can get to it as soon as possible. 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 an amazing framework or platform lacks in 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
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: For example: |
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]
----
----Writing Guidelines
We outline the most important writing style rules that must be followed when you contribute to Corteza documentation.
|
For more insight refer to this great article https://docs.openstack.org/doc-contrib-guide/writing-style/general-writing-guidelines.html. |
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 nicer and easier to read. It also makes it a bit shorter which is always a plus!
There are some exceptions when active voice should not be used:
-
When we are talking about errors it would sound like we are blaming the user!
-
it makes the sentence much longer.
Use the present simple tense
Users refer to the documentation to find out how something could be done. Lets give them the feeling like we are walking them through this process. This also makes it shorter and a bit easier to read then when other tenses are used.
|
When describing things like asynchronous data processing where it would not make sense to use use present simple tense, use the appropriate tense. |
Use second person
This makes it sound more engaging as it involves more people then just you and I. For example: "I have defined this feature that can be used to …" sounds way better as "We have defined this feature that you can use to …". The use of second person also removes gender-specific things.
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? Lets get straight to the point and tell our readers exactly what they want to know without waisting their time.
Keep things structured
When reading, people usually skim through the content or stop all together 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 an important bit.
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 contained in a nice 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 they way or even worse by just pasting a screenshot with no context what we are looking at. When including images make sure to indicate exactly what the image represents and make sure to provide an image caption that outlines what is going on in the image. This allows the reader to easily refresh their memory if they are already familiar with something but just want to refresh their memory.
|
Keep in mind that UI changes will require this images to be updated. |
User Roles
End-User
An end-user is someone who is tasked to perform some operations on the Corteza product or any of the integrations. In most cases, this users are not field experts so we should keep that in mind.
Administrator
An administrator is someone who is responsible to setup and maintain a Corteza instance. This involves everything from the actual deployment, maintenance and permission configuration. These users should be knowledgeable in this fields in order to perform the tasks in an effective manner.
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 just have it in both places. If we are smart about it, we can define smaller snippets that can be included into both parts.
Overview
Provide a high-level overview over the entire product. Explain to the reader "what exactly this is", what can be achieved and provide some examples what has already been done. We need to get our reader intrigued in this! Cover:
- Product Overview
-
Describe what the product is and what it’s not. Provide some example applications and possible solutions.
- Security
-
Provide a rough overview over the security system - users, roles, access control and so on. Don’t go that much into the details but give the reader a realistic overview over the security system and it’s capabilities.
- Architecture
-
Outline all of the important components and what they are and/or could be used for. Use all the fancy buzz words!
- Development and Contribution
-
Provide a quick outline on how to contribute, define all the available repositories and provide some links to resources. Provide some rules for issue tracking, documentation contributions, …
- Deployment
-
Provide a quick step by step guide on how to setup a fresh Corteza instance.
- Benchmarks
-
Provide some benchmarks, and of course some fancy charts to show the products capabilities.
- Road Map
-
Provide a road map for the near future.
|
Remember! This is meant for non-techy people, so keep it plain and simple. You can use some marketing buzzwords but that’s pretty much it. |
End-User Guide
Provide a high-level overview over all features from the end-user’s perspective. It should be as short and condensed as possible, as the end user doesn’t really care of all the technical details such as what protocols are used, what frameworks are used. 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 it's 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.Important things we need to address:
- APPLICATION_FEATURE_NAME should cover multiple smaller features
-
this allows us to create a shorter documentation that is much friendlier to the end user. For example, instead of creating multiple sections for Sending messages, Editing messages, 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 we define new sections Formatting text and Tagging users that focus only on that. For example:
= {PRODUCT_NAME} {APP_NAME_MESSAGING}
{PRODUCT_NAME} {APP_NAME_MESSAGING} is a cloud messaging application designed for communication between team members.
It can be used by any user that has the correct permissions.
[IMPORTANT]
====
If you can't access the application, contact your system administrator.
====
To access the application, ...
== Messages
// ...
=== Sending messages
// ...
// Replying to messages
// ...
=== ...We should also cover:
- Getting Started
-
Cover the first steps that the user should take to get up and running. For example how to register, how to login, how to change their username/email, …
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, editing module fields, creating new users, creating and assigning roles, and so on. We should also cover the process of setting up a fresh instance and all the initial steps. We shouldn’t focus on how to create an integration; that is what the integrators guide is for. The section should describe multiple sub sections 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 extend where an administrator will be confident with using it.
// Keep it as short as possible but do provide all the important details!Important things we need to address:
- APPLICATION_FEATURE_NAME should cover multiple smaller features
-
this allows us to create a shorter documentation that is much friendlier to the administrator. For example, instead of creating multiple sections for Creating users, Deleting users, 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 on role membership.
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. It should provide enough insight into the system, terminology and other bits such as extension development so that the reader is able to extend the base Corteza for either themselves or a client. The document should be written for field experts, so we shouldn’t worry about their limited knowledge on the subject. The section should describe multiple sub sections where each describes an application that Corteza defines; such as Corteza Messaging. Each sub section should specify how to setup/configure a specific area of the application; for example "Setting up a namespace". Make sure to keep the sub sections relatively small! For consistency we define the following structure:
= {APPLICATION_NAME}
// Provide a quick TL;DR of the application.
== {APPLICATION_SECTION_NAME}
// Describe the section in enough detail, that the integrator will be able to confidently perform the given task related to the section.For example:
= {PRODUCT_NAME} {APP_NAME_COMPOSE}
// ...
== Setting up a namespace
A namespace encapsulates data related to a specific area (in database terminology it is a schema).
For example, if we are working on a CRM system (defining additional modules, changing fields) we would work under the CRM namespace.
=== Creating a namespace
// Things related to how to create/update/delete the namespace
// ...
=== Administration
// Things related to the administration, such as permissions
// ...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.
- Extension Development
-
Describe in detail how the automation system works from the integrators perspective — how to create a new automation script, Corredor helper classes, API clients, … Go into details, but omit the implementation related specifics.
- Tips and Tricks
-
Hack down some findings, 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 sub sections 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 extend where a maintainer understands what parts of the system are involved when working on this feature (improvements, bugfixes, ...).Important things we need to address:
- APPLICATION_FEATURE_NAME should cover multiple smaller features
-
this allows us to create a shorter documentation that is much friendlier to the reader. For example, instead of creating multiple sections for Creating users, Deleting users, Editing users, … we can define a single Users section that gives the reader enough knowledge to understand what parts are involved.
Additional sections to 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.
Extensions
The purpose is to provide an overview of all available official extensions from the integrators perspective. Each extension should define it’s own 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 sub section further as you see fit.|
If you are developing your own extensions, provide your own documentation and don’t attempt to merge it here unless we agree on making it an official extension. |