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.