[simoncion]

In order to see the quality difference, you have to compare the docs to another project that you make extensive use of.

I know that Postgresql's and Erlang's documentation is really rather good. So, go use Postgresql or Erlang for a slightly non-trivial project, then -now that you know about the topic that the docs cover- compare the quality of the systemd documentation to the documentation of either other project.

Pay special attention to the documentation provided to folks who want to understand the internals of systemd, Postgres, or Erlang. AIUI, [0] systemd's internals documentation is woefully lacking.

[0] And as has been repeated by everyone I've ever seen try to use said documentation.

[witty_username]

True, systemd's documentation isn't very bad though, it's reasonable (lack of internal documentation is pretty common in many open source projects).

[simoncion]

Remember that this thread was sparked by otterly's comment: [0]

> The documentation for systemd and its utilities is second to none.

What little I've seen of systemd's user/sysadmin documentation leads me to believe that it is okay. I also understand that documentation is often the least interesting part of any project, and often sorely neglected.

However. Everyone I've heard of that tests out the Systemd Cabal's claim that

"Systemd is not monolithic! Systemd is fully documented and modular, so any sufficiently skilled programmer can replace any and all parts of it with their own implementation."

by attempting to make a compatible reimplementation has failed at their task [1] and reported that the internals documentation is woefully insufficient.

When you're writing software for general consumption, good user documentation is a requirement. After all, if noone can figure out how to use your system, "noone" will use it.

When you also claim that you go out of your way to provide enough documentation to allow others to understand the relevant parts of your internals, and be able to write compatible, independent implementations of your software, the quality of the documentation about your internals is now in scope for evaluation and criticism.

[0] https://news.ycombinator.com/item?id=10485095

[1] I am very aware that this task is made harder by the fact that it is large and thankless. :)