document documentation guidelines

[markus2330]

document documentation guidelines now can be found here:

https://www.libelektra.org/devgettingstarted/documentation

[kodebach]

Not sure if this appropriate here. But we should document all these guidelines within the repo. IMO it is not enough to link to some paper and an external page to explain decisions. There should at least be a short explanation within the repo, in case the external information goes away.

building block view for libs

If you are refering to this I actually think that's a horribly useless way of documenting our libraries.

1. Elektra is not an isolated system. In fact Elektra is one or multiple building blocks (depending on your view) of other systems. I don't see how you could produce a diagram documenting the relationships of things, if you don't know about the things outside Elektra.
2. These kinds of diagrams always require lots of time to create and then they have to be maintained. I don't think adding another easily outdated part to the docs is helpful.
3. It is very hard to find the right balance between too simple and too detailed. And it's even harder to do so, and produce something actually useful (IMO both diagrams are completely useless).

If we really want diagrams, they should probably defined with Mermaid. Then they can easily be updated by changing the code and are also rendered on GitHub.

[kodebach]

We probably should also have a CONTRIBUTING.md at the root of the repo that explains what too look out for and where all the guidelines for contributors are documented. See also https://docs.github.com/en/communities/setting-up-your-project-for-healthy-contributions/setting-guidelines-for-repository-contributors

[markus2330]

But we should document all these guidelines within the repo. IMO it is not enough to link to some paper and an external page to explain decisions.

I absolutely agree, will add!

If you are refering to this I actually think that's a horribly useless way of documenting our libraries.

I agree that this part of arc42 is not really ideal for FLOSS. I'll write something more specific to our situation, similar to plugins.

These kinds of diagrams always require lots of time to create and then they have to be maintained.

A few diagrams are very helpful for beginners.

IMO both diagrams are completely useless

They are not for you anymore, I also don't use them. They are useful, however, to get a first impression/overview what Elektra is composed of/what it can do, e.g., you see what lib depends on what or that Elektra has plenty of check and storage plugins.

If we really want diagrams, they should probably defined with Mermaid. Then they can easily be updated by changing the code

It looks like it is doing the same as dot. But I agree that this is a much more modern.

and are also rendered on GitHub.

It also has plenty of other integrations, e.g., GitLab, so it wouldn't be a lock-in situation.

[kodebach]

It looks like it is doing the same as dot.

I think that's the idea. Basically dot, but works in the browser.

It also has plenty of other integrations

Also for the popular docs website frameworks.

It also seems very easy to add to the website

[kodebach]

A few diagrams are very helpful for beginners.
They are not for you anymore, I also don't use them.

Yes, but I don't think the plugins diagram is very readable. I think it would be better to either reduce the number of plugins or show the same information in a different way, e.g. a table or some sort of color coding.

For beginners the diagram should also show some information they need and can understand. Showing the dependencies between all the libraries before people even know what the libraries do might be overwhelming.