\label{doc_contrib_documentation_md_md_doc_contrib_documentation}%
\Hypertarget{doc_contrib_documentation_md_md_doc_contrib_documentation}%
 This document gives guidelines for contributors concerning Elektra\textquotesingle{}s documentation. This document takes preference to the actual situation. If you see documentation not according to this document, please \href{https://issues.libelektra.org}{\texttt{ create an issue}}. Alternatively, you can directly fix it with your next PR.

\begin{quote}
Note\+: It is always allowed to improve the documentation, in every PR, even if the documentation fix is completely unrelated. Preferably are several PRs, though. \end{quote}
\hypertarget{doc_contrib_documentation_md_autotoc_md1661}{}\doxysection{Target Groups}\label{doc_contrib_documentation_md_autotoc_md1661}
We write documentation for three groups\+:


\begin{DoxyItemize}
\item User\+: Is a person who uses Elektra, e.\+g. an application using Elektra or one of Elektra\textquotesingle{}s tools like {\ttfamily kdb}.
\item Developer\+: Is a person who uses some library of Elektra within an application, tool or plugin.
\item Contributor\+: Is a person who does changes within Elektra\textquotesingle{}s repository.
\end{DoxyItemize}

There are 3 separate folders for these 3 groups\+:


\begin{DoxyItemize}
\item for users
\item \mbox{\hyperlink{md_doc_dev_README_doc_dev_README_md}{for developers}}
\item for contributors
\end{DoxyItemize}

\begin{quote}
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. tutorials. \end{quote}
\hypertarget{doc_contrib_documentation_md_autotoc_md1662}{}\doxysection{Orientation}\label{doc_contrib_documentation_md_autotoc_md1662}
Each documentation should clearly be oriented to one of these 3 directions\+:


\begin{DoxyEnumerate}
\item learning-\/oriented\+: First introduction is done via tutorials, they teach the fundamentals.
\item information-\/oriented\+: The README.\+md and API docs together are the references\+: They cover everything that someone needs to know about a \mbox{\hyperlink{doc_help_elektra-glossary_md}{module}}.
\item understanding-\/oriented\+: The \mbox{\hyperlink{doc_decisions_README_md}{doc/decisions}} explain the \char`\"{}\+Why?\char`\"{} something is done as it is done, i.\+e., the rationale.
\end{DoxyEnumerate}

In literature there is also goal-\/oriented 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?

\begin{quote}
Takeaway\+: Don\textquotesingle{}t try to combine different orientations in one document, instead split your documentation up in e.\+g. a README.\+md (information), tutorial (learning), decisions (understanding). \end{quote}
\hypertarget{doc_contrib_documentation_md_autotoc_md1663}{}\doxysection{Criteria}\label{doc_contrib_documentation_md_autotoc_md1663}
Elektra\textquotesingle{}s documentation must fulfill\+:


\begin{DoxyItemize}
\item Always write what {\bfseries{is}} not what you would like to have. Explanations must always refer to the current situation (as changed with your PR).
\item It is self-\/contained. It is not enough to link to some paper and an external page as explanation. All explanation must be within the repository, e.\+g., in case the external information goes away. This doesn\textquotesingle{}t apply if the authoritative standard lives outside of Elektra. Then you would write, e.\+g., \char`\"{}\+The toml plugin implements \mbox{[}this standard\mbox{]}(https\+://toml.\+io/en/v1.\+0.\+0), with following extensions\+:\char`\"{}. The extensions, however, again must be fully listed within our repository.
\item We use standard Markdown where possible, with only a few extensions\+:
\begin{DoxyItemize}
\item styled fenced blocks
\item {\ttfamily -\/ \mbox{[} \mbox{]}} option lists
\item {\ttfamily -\/ $<$word$>$\+:$<$line break$>$} description lists
\end{DoxyItemize}
\item The documentation should be as near the code as possible.
\end{DoxyItemize}

\begin{quote}
Takeaway\+: Include full API and Markdown documentation of the current situation directly in your PRs. \end{quote}
\hypertarget{doc_contrib_documentation_md_autotoc_md1664}{}\doxysection{Style}\label{doc_contrib_documentation_md_autotoc_md1664}

\begin{DoxyItemize}
\item Sentences are short and written in one line. I.\+e. lines usually end with {\ttfamily .}, {\ttfamily \+:} or {\ttfamily ;}. Avoid line breaks in the middle of the sentence.
\item Use active and strong verbs early in your sentences. \char`\"{}\+We\char`\"{} refers to the community around the Elektra Initiative.
\item Use headings and lists to keep a clear structure in the text.
\item Use examples and images to emphasize important points, don\textquotesingle{}t overuse emphasis in text (bold, etc.).
\item Spelling is American English with spellings as defined here.
\item It is consistent with our \mbox{\hyperlink{doc_help_elektra-glossary_md}{terminology}}.
\end{DoxyItemize}

\begin{quote}
Note\+: Please extend \mbox{\hyperlink{doc_help_elektra-glossary_md}{terminology}} and spellings as needed. \end{quote}
\hypertarget{doc_contrib_documentation_md_autotoc_md1665}{}\doxysection{Completeness}\label{doc_contrib_documentation_md_autotoc_md1665}
In general the documentation does not need to be complete. In particular, we do not want repetition of implementation details as documentation. \mbox{\hyperlink{doc_CODING_md}{Prefer to write self-\/documenting code}}. Nevertheless, there are a few must-\/haves\+:


\begin{DoxyItemize}
\item A README.\+md must be available for every module.
\item A man page (help/kdb-\/) must be available for every command (including external commands).
\item A tutorial must be present for every important concept.
\item Every documentation page must be listed in the Website\textquotesingle{}s structure.
\item Everything copied must be properly licensed in reuse.
\end{DoxyItemize}\hypertarget{doc_contrib_documentation_md_autotoc_md1666}{}\doxysection{Links}\label{doc_contrib_documentation_md_autotoc_md1666}
Generously use links but be very careful to create a coherent documentation (German\+: \char`\"{}roter Faden\char`\"{})\+:


\begin{DoxyItemize}
\item Clearly separate between prerequisites and further readings.
\item Prerequisites\+: Concepts people need to know before reading the documentation must be linked in the beginning.
\item When adding links, check if users cannot easily get lost in circles.
\item To link to Elektra\textquotesingle{}s files use internal links. Use absolute or relative links as appropriate. E.\+g. for files within the same folder use relative links.
\item For release notes use only external links to\+:
\begin{DoxyItemize}
\item \href{https://www.libelektra.org}{\texttt{ www.\+libelektra.\+org}} whenever possible, e.\+g. to tutorials, plugins, etc.
\item \href{https://master.libelektra.org}{\texttt{ master.\+libelektra.\+org}} to link to source files
\end{DoxyItemize}
\item For external links use https links, if available.
\item Only use {\ttfamily $\ast$.libelektra.\+org/$\ast$} links, avoid {\ttfamily github.\+com/\+Elektra\+Initiative/$\ast$} 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\+:
\begin{DoxyItemize}
\item \href{https://issues.libelektra.org}{\texttt{ issues.\+libelektra.\+org}} for the issue tracker
\item \href{https://pulls.libelektra.org}{\texttt{ pulls.\+libelektra.\+org}} for pull requests
\item \href{https://git.libelektra.org}{\texttt{ git.\+libelektra.\+org}} as main page to the source repository
\end{DoxyItemize}
\end{DoxyItemize}

\begin{quote}
Takeaway\+: Links are very helpful to readers. Make sure documentation can be read one after the other with these links (German\+: \char`\"{}roter Faden\char`\"{}). \end{quote}
\hypertarget{doc_contrib_documentation_md_autotoc_md1667}{}\doxysection{Templates}\label{doc_contrib_documentation_md_autotoc_md1667}
In general we use \href{https://arc42.org/}{\texttt{ arc42.\+org}} but we use specialized templates for different modules\+:


\begin{DoxyItemize}
\item \mbox{\hyperlink{md_src_plugins_template_README_src_plugins_template_README_md}{plugins}}.
\item \mbox{\hyperlink{md_src_libs_template_README_src_libs_template_README_md}{libs}}.
\item bindings.
\item tools.
\item \mbox{\hyperlink{doc_decisions_template_md}{decisions}} 
\end{DoxyItemize}