$darkmode
Elektra 0.11.0
Documentation

This document gives guidelines for contributors concerning Elektra's documentation. This document takes preference to the actual situation. If you see documentation not according to this document, please create an issue. Alternatively, you can directly fix it with your next PR.

Note: It is always allowed to improve the documentation, in every PR, even if the documentation fix is completely unrelated. However, separate PRs are preferred and can potentially get merged sooner.

Target Groups

We write documentation for three groups:

There are three separate folders for these three groups:

Takeaway: Every document must have a clear target group (user, developer or contributor). Sometimes it is clear from the directory, sometimes it must be explicitly stated, e.g. for tutorials.

Orientation

Each documentation should clearly be oriented to one of these three directions:

  1. learning-oriented: First introduction is done via tutorials, they teach the fundamentals.
  2. information-oriented: The README.md and API docs together are the references: They cover everything that someone needs to know about a module.
  3. understanding-oriented: The doc/decisions explain the "Why?" something is done as it is done, i.e., the rationale.

Literature mentions also goal-oriented concepts, but we prefer learning-oriented approaches. E.g. of course you might have the goal to write a new plugin. But why not also learn about plugins while creating a new plugin?

Takeaway: Don't try to combine different orientations in one document, instead split your documentation up in e.g. a README.md (information), tutorial (learning) and decisions (understanding).

Criteria

Elektra's documentation must fulfill:

Takeaway: Include full API and Markdown documentation of the current situation directly in your PRs.

Style

Note: Please extend terminology and spellings as needed.

Completeness

In general the documentation does not need to be complete. In particular, we do not want repetition of implementation details as documentation. Prefer to write self-documenting code. Nevertheless, there are a few must-haves:

Links

Generously use links but be very careful to create a coherent documentation (German: "roter Faden"):

Takeaway: Links are very helpful to readers. Make sure documentation can be read one after the other with these links (German: "roter Faden").

Templates

In general we use arc42.org but we use specialized templates for different modules: