$darkmode
Elektra 0.11.0
|
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.
We write documentation for three groups:
kdb
.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.
Each documentation should clearly be oriented to one of these three directions:
README.md
and API docs together are the references: They cover everything that someone needs to know about a module.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).
Elektra's documentation must fulfill:
- [ ]
option lists- <word>:<line break>
description listsTakeaway: Include full API and Markdown documentation of the current situation directly in your PRs.
.
, :
or ;
. Avoid line breaks in the middle of the sentence.Note: Please extend terminology and spellings as needed.
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:
README.md
must be available for every module.help/kdb-
) must be available for every command (including external commands).Generously use links but be very careful to create a coherent documentation (German: "roter Faden"):
*.libelektra.org/*
links, avoid github.com/ElektraInitiative/*
links. Create an issue if redirects are missing. Rationale: Then we can more easily move to other Git hosting platforms. Redirects created for this purpose:Takeaway: Links are very helpful to readers. Make sure documentation can be read one after the other with these links (German: "roter Faden").
In general we use arc42.org but we use specialized templates for different modules: