Structure of Documentation

[kodebach]

Continuing from #1164 (comment)

Maybe there should just be a quick overview of the required steps at the top.

I think that in most of our problems in the docu additional overviews/links/text won't help (except for, e.g., beginner devs, there we probably really missing something like that). We need to fix vague/misleading sentences.

I think an overview in the form of a table of contents for the entire docs would be immensely helpful. Currently it is very hard to find anything unless, you already know that things exists and have a rough idea where they could be.

Further the current split of docs is also problematic IMO. In the GitHub repo we have:

• decisions: For internal reference only
• dev: The README.md says it is the "developer's manual", but it is entirely unclear what information can be found there and who it is addressed to.
• help/man: Manpages, inherently (end-)user-facing, but sometimes also contains documentation in the sense of (behavioural) specification
• tutorials: Tutorials, all of which are "user"-facing. But what a "user" is differs, sometimes it is for application developers, sometimes it is for plugin developers, sometimes it is even of contributing to Elektra. The only commonality is that all are address to some person doing something for the first time, while consuming some API or system (e.g. build system) provided by Elektra.
• and a random pile of UPPERCASE.md files in doc

On the website it is even worse, the top-level menu groups things semi-randomly into "Documentation" or "Development" and from this top-level menu it is absolutely unclear which items have further sub-menus.

---

IMO we need to totally restructure this and split the documentation into 3 main groups divided by the target audience:

1. User: Anything that is addressed to a person, who wants to install and then use Elektra.
2. Developer: Stuff addressed to people using Elektra in applications and/or developing plugins, i.e. the consumers of Elektra's API.
3. Contributor: All the internal information targeted at people actually working on Elektra, i.e. the people that work on Elektra's API and functionality.

With this split some of the existing categories clearly belong only to one group. For example, "decisions" are only relevant for contributors, while manpages should be only relevant to users. Other categories, like tutorials, could be found in different groups depending on their target audience.

Yes, this system may require duplicating information. But this is intentional. For example, the full and detailed specification and explanation/reasoning of how key names work (KEYNAMES.md) or how libelektra-kdb works internally (some of the new docs in backend branch) are mostly only interesting to contributors.

Developers will want a pretty thorough explanation of how e.g. escaping works in key names, but they do not need information about the internal storage of key names or the in-depth reasoning why things are like they are. Therefore, we should have a separate more cursory document targeted at developers.

Finally, users only need a very basic understanding of how key names work, because any error the make or misunderstanding they had should be detected by tools and explained in error messages. Importantly, we can never expect that users read all of the documentation. Many users will just try things immediately or, if they don't have any at all idea, just quickly skim for sections that seem relevant. The documentation must reflect this expectation.

Endless tutorials without summaries will just result in half-understood information. Even worse, if the tutorial is essential the specification at the same time (yes, I'm also guilty of doing this for e.g. gopts and the high-level API). Then users may misunderstand things by skimming the docs and skipping the dry spec-like parts and the people working on Elektra misunderstand things because the do it the other way around and the skip the hand-holdy tutorial sections, which may still contain vital information.

I also think that actual tutorials, should be presented step-by-step more like Google Codelabs (see #1522). This would of course require major reworks of the website, but it would almost certainly help. There is a reason why a huge company that invest a lot of time and money into good documentation focuses so much on this format. When you are presented with smaller packets of information at a time, it is harder to miss something.

Additionally, different kinds of documentation should IMO be written by different people. It is a lot of work and not always possible with purely volunteers, but IMHO only the main specification and developer facing docs (e.g. API docs) should be written (and maintained) by the maintainer of a component. User facing documentation should be created by other people based on the docs provided by the maintainer. This serves two purposes: 1) primary docs provided by the maintainer are validated 2) user facing docs are actually written by people who tried to understand the thing from the outside.

Finally, I think man pages should never be the primary documentation, except for documenting options and arguments of commands. I would never think to read a man page to find out about anything other than command-line options/arguments, or some part of POSIX. But even for POSIX stuff I google it and the stuff that comes up happens to be man pages. The fact that you have to open the man page elektra-key-names to find out about the convention for key names in applications is horrible (Note: AFAICT this is actually the only location that says that this is the convention for key names, other places use it, but without any explanation). Sure it's nice that some stuff is documented in the man pages as well, in case someone is on a terminal only system. But it's 2022 the primary documentation should really not be man pages.

---

PS. I know this is a lot of text again, but the TL;DR is:

1. we should restructure our docs into groups targeted at specific audiences
2. we should differentiate between specification and tutorial, even if this means duplicating information
3. tutorials should not be walls of text, when you read a tutorial for X you want to know how to do X and not why X is this way and maybe how you could do A, B or C as well
4. man pages should never be the primary documentation (except for command line args)

[kodebach]

Just to be clear, the above is only my opinion and I'm open to suggestions, but it should be pretty clear to everybody that something needs to change.

Also changing all existing docs will be a lot of work yes, but IMO it's much more important that we (somewhat quickly) find a good target structure and writing style for our documentation. Once we have that, new documentation can be written with those guidelines in mind, even before all the old stuff is updated.

[markus2330]

I don't think we can treat the internal structure of documentation the same as the external structure. For the website I think your proposal makes a lot of sense. Structuring based on target audiences, in particular developers using Elektra and developers improving Elektra, would be a vast improvement.

I don't understand, however, how this should be applied to the folder structure. Please give specific suggestions.

tutorials should not be walls of text, when you read a tutorial for X you want to know how to do X and not why X is this way and maybe how you could do A, B or C as well

I agree. And we also need to make clear the target audience for every tutorial.

man pages should never be the primary documentation (except for command line args)

You know that, e.g., Linux was developed by implementing what the man pages say. We currently document the whole kdb tool via man pages and I do not see any reason to change this.

Once we have that, new documentation can be written with those guidelines in mind, even before all the old stuff is updated.

Yes, I see that you somehow had doubts in the new-backend branch how to write the "dev" docu. Such internal docu is one of the most difficult to write, as the details are tedious and you cannot abstract from details because the goal is that people actually understand the whole code. I don't think restructuring can solve this problem.

[kodebach]

You know that, e.g., Linux was developed by implementing what the man pages say.

Yes, but that was in 1991 and man pages were probably the only public documentation of Unix. The world is different now, most people prefer a web browser over a terminal window.

We currently document the whole kdb tool via man pages and I do not see any reason to change this.

That's fine, kdb is a command line tool. In this case I agree that man pages should be the primary documentation.

What I disagree with is mostly the man7 stuff, e.g. elektra-glossary. All this general information about Elektra can of course be documented in man pages, but this should not be the primary source. If I didn't know I'd never check man pages for information about Elektra's namespaces (elektra-namespaces) or the bootstrapping procedure (elektra-bootstrap).

Just to be clear, I didn't check everything, maybe all this information is actually documented elsewhere too. But my point is things like namespaces and bootstrapping should primarily documented elsewhere, and the man pages should just be a summary for users.

Yes, I see that you somehow had doubts in the new-backend branch how to write the "dev" docu.

That's partially true. I did have some troubles. But some of the existing docs was also originally addressed to myself as future reference and not actually intended as the final docs. Other parts are not documented at all, since I wrote the code first and then didn't have time to write the docs (e.g. the new internal structure of struct _KDB).

I don't think restructuring can solve this problem.

I would help with some of my issues. For example, I had no idea where to put the docs. It's also not clear with the current structure, whether duplicate information is fine or considered a bad thing. If it was clear that we have separate docs for users, developers and contributors then it is clear that some stuff must be duplicated. It is also clear where you'd start. Either you start with user docs and work out the implementation later, or you start with contributor docs writing about all the implementation decisions and then work your way towards user facing docs.

I don't think we can treat the internal structure of documentation the same as the external structure. [...] I don't understand, however, how this should be applied to the folder structure.

I think it help with maintaining the documentation, if the internal structure mimics the external structure. It is just easier to get familiar with a single structure. Also AFAIK many of the doc-site generators actually use the folder structure to generate the website structure.

Please give specific suggestions.

This depends on how we generate the documentation website. Some frameworks have limitation in what folder structure is and isn't possible.

Some examples of site generators: MkDocs, Sphinx, Docusaurus

[markus2330]

That's fine, kdb is a command line tool. In this case I agree that man pages should be the primary documentation.

👍

should primarily documented elsewhere

About the other man pages I do not have a strong opinion. What is your suggestion where to put them?

whether duplicate information is fine or considered a bad thing.

Of internals: duplication is a bad thing. For external stuff (e.g. API) duplication is good: we want many examples, tutorials, etc.

Some examples of site generators: MkDocs, Sphinx, Docusaurus

MkDocs and Docusaurus looks quite similar to what our website already does. Sphinx could be interesting as it could replace Doxygen and the website. But it is probably way beyond the time budget we have.

I think for now we should discuss slow improvements what we can do now and before 1.0: moving around stuff so that we can open the files with the text editor and that they are rendered with the homepage (and sometimes doxygen).

To start with concrete ideas, within doc:

• we rewrite help/elektra-* so that is specifically for end users on the command-line
• we create a a "user" folder, where some of help/elektra-* and most of the ALL_CAPITALS.md files get moved. These files are for reference information, complementing the tutorials. There should be some substructure to avoid chaos.
• we make substructure in dev: this is what only Elektra developers need to know. Here there shouldn't be any duplication.
• obviously doc/README.md needs to be rewritten: explaining what "dev" and "user" is, where duplication is allowed etc.

[kodebach]

What is your suggestion where to put them?

Right now: Leave them. Long-term: Somewhere on the website, assuming a sensible website structure.

I think we can assume that people who are learning Elektra have access to a browser and the internet. If we really want to provide a local copy, we could ensure that the website framework we use produces static HTML. Then we could package and ship that in a docs package (with doxygen, etc.)

But it is probably way beyond the time budget we have.

IMO this here is the a good issue for a thesis. There are many students with interests in web development. To just structure and build the docs, you don't really need any C knowledge or really work on Elektra (in fact it's probably better to not know the code). For the scientific part, the thesis could focus on quality of FLOSS documentation. Either by evaluating our docs methodically, or maybe by comparing against other FLOSS projects.

As for the contents of the docs: The user facing stuff could be written by the student as part of the thesis (here it's better to have less internal knowledge to make the docs beginner friendly). The other stuff of course has to be written by someone with more knowledge of Elektra. But once we have a base structure writing the docs is just a question of time.

To start with concrete ideas, within doc:

If you make this a thesis topic, I'd wait maybe a month or two to see if we find someone for this. Otherwise, yes I agree with most of the ideas. Just one thing: I miss the distinction between "contributor" and "developer" (i.e. external).

What I'd also do: Categorise all files in doc as "user", "developer", "contributor" or "mixed". This could be done in a GitHub issue, a file in a PR or by moving files around. I would only categorise something as "mixed" if it is really unclear who the file targets. For the files that are mostly one category, with a bit of other stuff, I'd just create a tracking issue that the file needs to rewritten/split up, e.g. a mostly contributor-facing file, but there is some stuff that could be relevant to outsiders.

[markus2330]

It is not like that I never tried to have someone on this topic or that nobody ever worked on it. Let us face it: it is very unpopular and no "outsider" (i.e. only working on docu) will give satisfactory results. So every dev needs to contribute their part.

I would like to have the low-hanging fruits fixed before the lecture starts, within the new-backend branch. The situation currently in new-backend branch is not okay. I hope you help, as most of the stuff of new-backend is only in your head 😉

[kodebach]

I would like to have the low-hanging fruits fixed before the lecture starts, within the new-backend branch.

I'm not sure there is any low-hanging fruit in terms of structure. We might be able to move some files around. But after looking around a bit, I'm not even sure that's possible. AFAICT the current website expects a certain structure. So we might be limited in what is possible and also useful.

As for content, I think splitting up and restructuring existing docs will be quite time consuming. IMO that should only be done, when it is clear what the exact structure of the new docs will be.

The situation currently in new-backend branch is not okay.

I never claimed the docs on new-backend are done. In fact there are many TODOs that say the opposite. I also repeatedly said that merging new-backend before the lecture will be difficult (or impossible).

However, there are already mountpoints.md, kdb-operations.md and backend-plugins.md. These are what I'd call "Contributor" docs. They are like specification to define what should happen. They are not perfect, but they cover the important bits. I'll try to go through them and update them a bit this weekend.

I hope you help, as most of the stuff of new-backend is only in your head

I don't think anything is purely in my head. AFAIK I wrote all my ideas down somewhere. Either there is a TODO (and therefore it should be in #4407) or it's in one of the docs files that have been added in new-backend. I might not have written down all the details, but that's because the details will change when we write the code anyway. I'm also happy to answer any specific questions.

One thing I haven't done and definitely won't do soon is check and update existing docs. Because of the unstructured and disorganised nature of our docs that is a massive task and probably requires reading all the docs. But only having (accurate) "Contributor" docs for now is fine IMO. There shouldn't be any "Users" or "Developers" for the new-backend branch that aren't also "Contributors".

---

Note The rest of this comment is an explanation, why I think a thesis topic might still be a good idea, even if it might not solve the whole issue. If you don't agree, no need to discuss any of details below, just say you don't want to make it a thesis topic ;)

I think this is very much a matter of how the thesis topic is described. For this thesis I would see Elektra similar to how lcdproc related to my thesis. It's just a case study subject. IMO the focus of the thesis should be developing a website for the documentation of a FLOSS project. It just so happens that this project is Elektra.

Regarding the contents of the docs. IMO it would already be a huge help, if someone looked into the different frameworks for docs websites, chose one and created the setup for us. Even if the don't create new docs and just use existing text and some lorem ipsum style filler, it would be a good start. Ideally though the person would at least learn enough about Elektra so they can create some user-facing docs, e.g. some general docs about using Elektra to configure applications (maybe someone who took the CM course).

Working out a good structure for the docs beyond my very rough split "User", "Developer" and "Contributor" is a time consuming process, if you want to do it right. It is also something that could be done very scientifically with lots of studies. Similarly, evaluating different docs frameworks takes time, especially if you want to end up with something that doesn't need to be swapped in a few years. All this needs time I don't have, but someone working on a thesis might be willing to invest. Actually filling the new website with information in the end, is a quick task in comparison. Most of Elektra is already documented somewhere, so we just need people who know Elektra to redistribute the information into the new structure. But first the structure needs to be worked out.

A benefit of having a better website with a well defined structure would also be that it should be easy to spot, when a topic lacks documentation. As an example, if there was a navigation tree docs -> developer -> libs -> ... and then there was no entry for libelektra-opts, you immediately know what needs documentation. In the current situation you have to look through almost the entire website, because "it might be documented somewhere".

[markus2330]

I'm not sure there is any low-hanging fruit in terms of structure. We might be able to move some files around. But after looking around a bit, I'm not even sure that's possible. AFAICT the current website expects a certain structure. So we might be limited in what is possible and also useful.

The website shouldn't expect expect anything. It has a separate structure defined in src/tools/website/resources/structure.json.in which could be totally different. (Obviously you will prefer to reuse README.md already containing long lists of e.g. tutorials but actually you could list any files.)

I never claimed the docs on new-backend are done. In fact there are many TODOs that say the opposite. I also repeatedly said that merging new-backend before the lecture will be difficult (or impossible).

The problem is that in February it will be even more impossible (because in summer-term students actually rely on a working Elektra, I cannot risk doing such a big change there), so we are talking about waiting at least a year. Who knows if anyone will be motivated to put so much work in this super-old branch, which already proved trice that it is unmergable. Most people working now on new-backend branch will be hardly available by then. I don't think our small resources allow that we have two branches for such a long time. Please fix as much as possible so that we can do this merge asap.

I'll try to go through them and update them a bit this weekend.

Thank you! 💖

There shouldn't be any "Users" or "Developers" for the new-backend branch that aren't also "Contributors".

Maybe. Nevertheless it should be very clear for contributors which information is up-to-date. And this information should be easy-enough to read for FLOSS beginners.

if someone looked into the different frameworks for docs websites, chose one and created the setup for us.

This is a bad idea. Introducing new stuff is easy, making it nice is the hard part. Even a good structure alone is not enough, we need a red line that guides through the docs. This is impossibly done by "someone", it must be done by us, people who know the big picture.

In the current situation you have to look through almost the entire website, because "it might be documented somewhere".

No, in my current logic at least minimal README.md should be src/libs/opts (if src/libs/README.md did not already explain everything). Getting the folders where README.md is missing is probably the easiest thing to check.

[kodebach]

It has a separate structure defined in src/tools/website/resources/structure.json.in which could be totally different.

I saw that. I just wasn't sure how flexible this is since it is something totally custom. However, I guess we could always list all docs files individually instead of relying on the more advanced features.

The problem is that in February it will be even more impossible

I also didn't say that we should wait until February to merge new-backend.

Most people working now on new-backend branch will be hardly available by then.

That would be a good thing. Since it would mean their work is finished, i.e. new-backend would be much closer to merge.

do this merge asap.

I'm totally with you on that. But the key here is the p i.e. possible. We need to define what conditions must be fulfilled to make merging new-backend possible. See #4483

Let's move the discussion about merging new-backend (i.e. the stuff above this line), to #4483.

---

There shouldn't be any "Users" or "Developers" for the new-backend branch that aren't also "Contributors".

Maybe.

To clarify what I meant: There shouldn't be anyone using new-backend who isn't capable and willing to look at the source code or at the very least ask questions in this repo. So there shouldn't be anyone who develops an application or plugin using Elektra just by looking at the docs, and there certainly shouldn't be anyone who wants to configure an application that uses Elektra with just the docs.

Nevertheless it should be very clear for contributors which information is up-to-date. And this information should be easy-enough to read for FLOSS beginners.

My suggestion would actually be this: We'll go through the docs and simply delete everything that is obviously incorrect/outdated. At the same time, we create an issue to document everything we removed from the docs. Then we can assess what needs new documentation, and what is already covered elsewhere. The approach is a bit drastic, but IMO it is much better to have no documentation at all than to have incorrect docs, especially for FLOSS where people are very much encourage to ask questions if they need help.

Introducing new stuff is easy, making it nice is the hard part. Even a good structure alone is not enough, we need a red line that guides through the docs. This is impossibly done by "someone", it must be done by us, people who know the big picture.

Yes, "making it nice is the hard part". That's exactly why we need someone who puts in the time and evaluates different approaches to docs websites. Not just from the standpoint of "how does the website look?", but also things like "how well does website generation integrate with CI?", "what are the requirements for the git repo?", "is the website structure flexible?", etc.
As you can see these are mostly technical questions I want answered. That's why I think this is possible as a thesis without requiring a good understanding of Elektra. In fact the whole thing could be done completely without Elektra. But of course then it might not actually help us.

So I would suggest placing the RQ for the thesis along the lines of: "What is the best framework to generate the documentation website for a FLOSS project like Elektra?" The person working on this wouldn't need to know details about Elektra, but we would have to tell them what requirements we have e.g. do we want docs outside of doc, or is a single central folder okay?

Of course, if you don't think that is a good thesis then leave it. But I think without making this a thesis, we will just pick a random framework based on some cursory look at docs & examples and we might regret that at some point. I don't think any of us will want to spend the necessary time to truly evaluate these frameworks.

In the current situation you have to look through almost the entire website, because "it might be documented somewhere".

No, in my current logic at least minimal README.md should be src/libs/opts (if src/libs/README.md did not already explain everything). Getting the folders where README.md is missing is probably the easiest thing to check.

Not sure what you mean with "your current logic", but I meant "as things are in the repo right now". And in that situation anything might be documented anywhere. For your specific example:

1. The rules are already confusing. Either src/libs/README.md explains everything for all libraries, or it is simple a list of links with one sentence explanations. Anything in between is too complicated and will create a mess. We need 100% clear rules for documentation. I say that, because I know that I myself have put docs in many different places over the time, because there weren't any clear rules and nobody cared (at least no one complained in code reviews).
2. What is a "minimal README.md"? What should the README.md files described? I think this is only clear for plugins, where with very few exceptions the README.md contains the entire documentation for the plugin (e.g. gopts of course doesn't duplicate all the libelektra-opts docs).

[markus2330]

My suggestion would actually be this: We'll go through the docs and simply delete everything that is obviously incorrect/outdated. At the same time, we create an issue to document everything we removed from the docs. Then we can assess what needs new documentation, and what is already covered elsewhere. The approach is a bit drastic, but IMO it is much better to have no documentation at all than to have incorrect docs, especially for FLOSS where people are very much encourage to ask questions if they need help.

I don't think that creating issues of missing docu by us leads anywhere. We should fix as much as possible ourselves and steadily improve docu in every PR. Only if an outsider sees something is missing, an issue is useful (in form of a question what the person didn't understand). Thus question issues should always be fixed in the docu, so that it will be clear for the next person.

So I would suggest placing the RQ for the thesis along the lines of: "What is the best framework to generate the documentation website for a FLOSS project like Elektra?"

We already had a thesis more-or-less like this. And the result is the website we currently have.

The rules are already confusing. Either src/libs/README.md explains everything for all libraries, or it is simple a list of links with one sentence explanations. Anything in between is too complicated and will create a mess. We need 100% clear rules for documentation. I say that, because I know that I myself have put docs in many different places over the time, because there weren't any clear rules and nobody cared (at least no one complained in code reviews).

Ok, then let us add a README.md for all the libs, like for plugins, tools and bindings.

What is a "minimal README.md"? What should the README.md files described? I think this is only clear for plugins, where with very few exceptions the README.md contains the entire documentation for the plugin (e.g. gopts of course doesn't duplicate all the libelektra-opts docs).

We use https://arc42.org/, as you already noticed for decisions etc. For the building blocks we need more specific templates, like we have for plugins. I created #4486 to fill the missing holes. Which other holes do we have?

[kodebach]

I don't think that creating issues of missing docu by us leads anywhere.

It would tell us about the current state of our docs. Right now I have no idea, how much of the docs really are outdated.

We should fix as much as possible ourselves and steadily improve docu in every PR.

Of course fixing things immediately would be better. But there are still many reasons why what's not always easy.

For the bigger problems (e.g. updating outdated information) you need time, which we don't always have. It's much better to create an issue for later than to just ignore it. Even for smaller things that can be fixed quickly, creating an issue is still better than throwing the change into some unrelated PR, if you don't have time to handle a separate PR right now.

Thus question issues should always be fixed in the docu, so that it will be clear for the next person.

"Always" is a strong word. It really depends on the question. Sometimes the information is already there and some just didn't understand it. Of course rewording might help in such cases, but not just because a single person would benefit.

Ok, then let us add a README.md for all the libs, like for plugins, tools and bindings.

That's definitely a good start (and something that could be enforced by CI). But I think we also need some place in doc to put extra docs for a library. The README should cover the basics, but to keep things readable READMEs of complex libraries (like opts or notification) should probably link to one or more additional file.

We use https://arc42.org/, as you already noticed for decisions etc.

Actually, I didn't know that. I now saw that it is mentioned in doc/decisions/README.md, but I've never actually read that file because it always seemed like "just an index".

[markus2330]

It would tell us about the current state of our docs. Right now I have no idea, how much of the docs really are outdated.

We are actually in a quite good situation: not much is outdated. As a matter of fact: I think the situation was never as good as it is now. The last huge change, the changes of keynames is now afaik fully fixed in the documentation. I did not come across wrong parts for quite some time now.

Of course new-backend will make the situation a bit worse again. But the worst can be avoided if you (quickly) look across the whole documentation and remove the parts that get wrong because of new-backend. There is no need to rewrite it now, this we can do during the next term. But at least the wrong information should be removed. Unfortunately, I cannot do it my self, as I am not acquainted enough on the changes of new-backend myself to decide.

It's much better to create an issue for later than to just ignore it.

Maybe yes, but maybe the documentation was useless after all. I think there is quite some docu, e.g. in doc/dev/ which is actually not so important and probably does not need to be rewritten. So I encourage you to simply remove it if new-backend makes it wrong now.

Even for smaller things that can be fixed quickly, creating an issue is still better than throwing the change into some unrelated PR, if you don't have time to handle a separate PR right now.

I disagree. Docu fixes are one of the things I would always accept in PRs. If the person came across this docu while working on the PR, why not change it within the PR?

"Always" is a strong word.

Exactly.

It really depends on the question. Sometimes the information is already there and some just didn't understand it. Of course rewording might help in such cases, but not just because a single person would benefit.

I didn't came across a single question which couldn't be used as insight to somehow improve the documentation. And especially beginners are one of the greatest source of inspiration. E.g. have a look at #2468 (only later we got distracted by improving the error message too, which seems to be difficult)

The README should cover the basics, but to keep things readable READMEs of complex libraries (like opts or notification) should probably link to one or more additional file.

I'll write more about it hopefully soon in #4486 but the first ideas are:

• information-oriented: the README.md and API docs together are the references: they cover everything that someone needs to know about a module (i.e., either lib, plugin, backend, tool)
• learning-oriented: easy introduction to some topics via tutorials
• understanding-oriented: the decisions explain the "Why?" something is done as it is done
• goal-oriented: this I am yet not so sure about how much room we should give it. Imho often a learning-oriented approach is better. 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?

I now saw that it is mentioned in doc/decisions/README.md, but I've never actually read that file because it always seemed like "just an index".

It is basically a template system. But the problem is that templates are basically only a "TODO-list". If you do not know what the whole gist of it is, templates do not help at all.

[kodebach]

We are actually in a quite good situation: not much is outdated.

It's hard to say without reading and checking everything. For example, I'm not sure this is fully correct anymore. Similarly. this reads as if we are unsure what the internal structure of a KeySet should be. However, AFAIK we're pretty confident that the combination of sorted array and OPMPHM is quite good.

The last huge change, the changes of keynames is now afaik fully fixed in the documentation.

It was pretty easy to find almost all instances of keynames with a simple regex. Outdated concepts and changed ideas are much harder to find.

But the worst can be avoided if you (quickly) look across the whole documentation and remove the parts that get wrong because of new-backend. There is no need to rewrite it now, this we can do during the next term. But at least the wrong information should be removed. Unfortunately, I cannot do it my self, as I am not acquainted enough on the changes of new-backend myself to decide.

Yes, I will do that. I already started with doc/dev/data-structures.md in #4484.

I'll also start an issue with stuff that should be documented again. If nothing else, it should be helpful for FLOSS.

I think there is quite some docu, e.g. in doc/dev/ which is actually not so important and probably does not need to be rewritten.

I think the problem with doc/dev is that nobody really knows what's supposed to be in this folder. That's why I think we need to split between "Developer" and "Contributor". For example, the explanations about Trie vs. Split and the OPMPHM in doc/dev/data-structures.md might be useful for contributors who need to know why we did things in a certain why and how exactly things work. But other stuff, e.g. information about iterators (doc/dev/iterators.md) or the plugin framework is useful to external developers too. That should be in a separate place. There is also stuff in doc/dev (e.g. doc/dev/error-categorization.md) that could (at least partially) be useful to users.

If the person came across this docu while working on the PR, why not change it within the PR?

Sure we can accept it, but we also have to be careful to keep PRs focused and to avoid overlap. If two people come across the same problem and fix it in different ways, we just get conflicts. That's why creating an issue is better. Then the second person would see that there is already an issue and if the first person fixed it in their PR, that should also be linked in the issue.

Of course if it's just a typo or a missing word or something like that, then I wouldn't create a issue and no separate PR either.

information-oriented: the README.md and API docs together are the references: they cover everything that someone needs to know about a module (i.e., either lib, plugin, backend, tool)

I think this the main area where we need more structure. AFAICT there are no guidelines where to put such docs. IMO this also needs to be split by target audience. Docs about "this is how kdbGet works internally" and "this is how you use kdbGet" should not be in the same place. The second group doesn't are about the first part.

I think we need a clear place beyond the README to put such docs. The API docs alone cannot cover everything.

learning-oriented [...] goal-oriented

IMO these should be combined. Tutorials should always have a goal (e.g. "how to write a backend plugin"), but must also teach the reader the important concepts related to this goal (e.g. "how does a backend plugin communicate with libelektra-kdb"). However, a tutorial stay focused and use references to other docs extensively. I think people that look for a specific tutorial mostly want to achieve a goal, if we put too much extra information in, people stop paying attention and start skimming for the parts they need.

[markus2330]

There seems to be a misunderstanding: I asked "only" about removing docu that is now definitely incorrect because of changes in new-backend.

It's hard to say without reading and checking everything. For example, I'm not sure this is fully correct anymore.

Thank you for pointing it out. 79b572d

Similarly. this reads as if we are unsure what the internal structure of a KeySet should be. However, AFAIK we're pretty confident that the combination of sorted array and OPMPHM is quite good.

Yes, I totally agree. c4ccc27

Yes, I will do that. I already started with doc/dev/data-structures.md in #4484.

💯 💞

split between "Developer" and "Contributor"

I agree, will add this in #4486

Sure we can accept it, but we also have to be careful to keep PRs focused and to avoid overlap. If two people come across the same problem and fix it in different ways, we just get conflicts. That's why creating an issue is better. Then the second person would see that there is already an issue and if the first person fixed it in their PR, that should also be linked in the issue.

I think you overrate issues. It is also work to find duplication within issues. And issues do not get any work done, PRs do. It rarely happens that two PRs tried to fix the same problem (only with the first wave of FLOSS PRs it happened). The main problem with issues is that they need to stay very focused, otherwise they actually talk about many problems and problems get forgotten, contrary to what an issue tracker actually promises to help with.

This is also why I started #4492, simply discussing about it would have lead to nowhere.

I think we need a clear place beyond the README to put such docs. The API docs alone cannot cover everything.

Fully agree, will do in #4486

[kodebach]

There seems to be a misunderstanding: I asked "only" about removing docu that is now definitely incorrect because of changes in new-backend.

No I got that, but if I spot something obviously wrong for other reasons (e.g. stuff about internal iterators). I should probably do something about that too. Should I remove that as well or create an issue about it?

I think you overrate issues. It is also work to find duplication within issues. [...]

I think this a matter of how we work. I think issues can be useful. I also think PRs should only be for concrete work not for endless discussion. For example, I absolutely dislike the decision PRs. IMO they are very confusing and it would be much better to have a discussion first and then summarize the results in a decision. Once the decision exists there shouldn't be a lot of discussion anymore (maybe about the wording). Finally, I really think we should use GitHub's discussions a lot more. I think the "multiple comment chains" system would make broad discussions like this one much better.

Those are my opinions. I don't really want to discuss them right now. It won't really lead anywhere. So let's just continue with the system we have.

[markus2330]

Should I remove that as well or create an issue about it?

Yes, if you are not sure what to do (e.g. fix/remove) please create an issue. I plan to do a review of the new-backend branch.

I think this a matter of how we work. .... So let's just continue with the system we have.

The main system we have is continuous improvement. If something does not work well we need to be able to adapt.

Imho at the moment we over-discuss in issues. I would prefer more suggestions in PRs.

[kodebach]

I would prefer more suggestions in PRs.

My problem with that is that the first suggestion often needs a lot of work and those PRs and their discussions then become overly complicated to read, because GitHub hides (at least some) comments for old commits as "outdated" by default.

Like I said, I think we should use Discussions more for abstract discussions like this one. I don't think there is any point in creating a PR with an idea that one person had, if there isn't at least a second person that agrees with the idea. That just results in wasted work creating PRs. However, I agree as soon as there are some concrete shared ideas, a PR can be useful (like we both did with #4484 and #4492)

[markus2330]

My problem with that is that the first suggestion often needs a lot of work and those PRs

We also need more focus in PRs. In such situations the first PR should only be a very high-level sketch of what should be done, either a decision, API, man page, etc.

and their discussions then become overly complicated to read, because GitHub hides (at least some) comments for old commits as "outdated" by default.

Yes, I agree. We need to create new PRs in every stage of development. (E.g. New PR after decision.)

Like I said, I think we should use Discussions more for abstract discussions like this one. I don't think there is any point in creating a PR with an idea that one person had, if there isn't at least a second person that agrees with the idea. That just results in wasted work creating PRs.

I think you underestimate the time consumed by discussions in issues. In computer science thinking time is much more expensive than expressing time. There is not much difference in cost if you express something in an issue or PR (e.g. writing a decision or also draft code). There is a huge time difference if you come up with something well-thought compared to some initial idea. FLOSS must be open to PRs that did not have any previous discussions. I aim to that we get there.

However, I agree as soon as there are some concrete shared ideas, a PR can be useful (like we both did with #4484 and #4492)

🚀

[kodebach]

the first PR should only be a very high-level sketch

Even this high-level sketch is not always something that can be agreed upon. Or it is so high-level that is essentially useless, at least unless to keep in the repo. For example, creating a PR with a decision just for "we want to make meta:/default work with type" would be useless, but anything more detailed might lead to long discussions and derail the PR.

We need to create new PRs in every stage of development. (E.g. New PR after decision.)

Closing existing PRs and creating new ones after significant changes to a decision doesn't make the problem of "loosing a comment thread" any better.

I think you underestimate the time consumed by discussions in issues.

I'm well aware of how much time we spend on discussions. The whole reason I suggested using GitHub's Discussion page is that I think it would make things more efficient and reduce the time spent on discussions.

In computer science thinking time is much more expensive than expressing time.

But when I made concrete proposals that just lead to the same or even longer discussions (see e.g. #4246).

There is not much difference in cost if you express something in an issue or PR (e.g. writing a decision or also draft code).

Actually writing a proper decision takes a lot longer for me than to write a rough draft proposal in an issue. Maybe you just want that rough draft in a file in a PR. But that still takes a lot longer for me. I need to create a branch, create the file, push, create the PR, etc. instead of just opening https://github.com/ElektraInitiative/libelektra/issues/new and starting to write.

There is a huge time difference if you come up with something well-thought compared to some initial idea. FLOSS must be open to PRs that did not have any previous discussions.

I have often put quite a lot of thought into an idea, even before I wrote an issue. My proposals are almost never a "first idea for X". Instead they most often are "first way to do X for which I didn't immediately see problems".

For "simple" things of course a PR can just be created. Creating a new validation plugin to check GPS coordinates doesn't need a discussion. Just create a PR and any concrete issues will be brought up in a code review.

But for the big issues it is certainly not the best use of our time to create PRs out of the blue. Figuring out all the details to create an implementation for big feature, instead of asking "do we want to do it like this?" is not a good way to spend time.

[markus2330]

Closing existing PRs and creating new ones after significant changes to a decision doesn't make the problem of "loosing a comment thread" any better.

Closing obviously not. But merging would.

But when I made concrete proposals that just lead to the same or even longer discussions (see e.g. #4246).

Yeah but that happened because we misused PRs as discussion forum. There was not so much review going on.

I need to create a branch, create the file, push, create the PR, etc. instead of just opening https://github.com/ElektraInitiative/libelektra/issues/new and starting to write.

As said, the "create the file, push, create the PR" etc. should be nearly nothing compared to thinking about the content. If this is not the case, something is fundamentally wrong.

I have often put quite a lot of thought into an idea, even before I wrote an issue. My proposals are almost never a "first idea for X". Instead they most often are "first way to do X for which I didn't immediately see problems".

Yes, I know. And you are also the person who is writing (by far) the most decisions. So statements here are not really about you.

But for the big issues it is certainly not the best use of our time to create PRs out of the blue. Figuring out all the details to create an implementation for big feature, instead of asking "do we want to do it like this?" is not a good way to spend time.

I cannot agree with it in general. There are plenty of examples of huge progress with large PRs out of the blue. For me, "the way of the middle" is decisions or user-interface description PRs out of the blue, detailed enough that it could be implemented without surprises for the person who was in favor of the initial PR.

[kodebach]

Closing obviously not. But merging would.

Merging is only an option if some consensus reached and the controversial parts are removed before the merge. Even then you loose the context from the old PR.

Yeah but that happened because we misused PRs as discussion forum. There was not so much review going on.

Exactly, and yet you prefer PRs over issues. Which are at least more discussion-like. Of course the Discussions tab is what we should probably use...

If this is not the case, something is fundamentally wrong.

Well for one, I need to be on a PC where I have the repo checked out. Opening a new issue just needs a browser.

But it is more about the fact that, i also need to think about where to put the file. If I should split it into multiple files, etc. And finally normally when I create a file like a decision, I tried to immediately write it in a way that is mergeable. So add the proper context where needed, etc. In an issue I just assume that either, people know what I'm talking about, or they will ask. You can really ask a static file in a repo...

And you are also the person who is writing (by far) the most decisions.

Not by choice... AFAICT you want everything in a decision, and you want decisions to be focused. So I need many to cover all the API-related changes that in principle we already agreed on...

And these API-related changes are really not something were I want to put in the time to implement them, only for someone to say "actually let's do it differently".

[markus2330]

Merging is only an option if some consensus reached and the controversial parts are removed before the merge. Even then you loose the context from the old PR.

Not in decisions, as all discarded ideas should still end up in "Considered Alternatives".

If I should split it into multiple files, etc.

The same needs to be considered when writing issues!

people know what I'm talking about, or they will ask

This is probably the reason why there are only 2 people in most discussions.

AFAICT you want everything in a decision, and you want decisions to be focused.

Gladly I can tell you: absolutely not! Only the major decisions which either:

1. shape the whole framework or
2. there is a controversy

should be put into decisions.

And these API-related changes are really not something were I want to put in the time to implement them

Yes, then better to have a decision where we explicitly agree on something.

[kodebach]

Not in decisions, as all discarded ideas should still end up in "Considered Alternatives".

Merging a decision with just "Considered Alternatives" and without an actual decision also seems wrong.
Opening a new PR with the "Considered Alternatives" from the PR comments now in the file, to reduce the clutter in PR, might be good idea, however.

The same needs to be considered when writing issues!

Not in the same way. Yes, unrelated topics should be separate issue. But issues only have one target audience (Elektra contributors). But for decisions, yes issues and files are similar.

This is probably the reason why there are only 2 people in most discussions.

The reason IMHO is also that most of the people working on Elektra do it for their thesis or the FLOSS/CM course. Very few of them know much about Elektra beyond the part they contributed.

---

See also #4514 (comment) (bottom bit): I agree that creating a PR as soon as there is a possible solution, with at least some chance of being accepted, is a good idea. But creating a PR that just say "this is the problem" is stupid in my mind. That is clearly what issues are for, state a problem (be it a bug, or a missing feature) and find a solution for it.

[markus2330]

superseded by #4501