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.