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.