For instance, I wanted to know why my custom systemd.conf unit file is causing my custom daemon to restart whenever the Ethernet cord gets unplugged or its netdev goes offline.
Unfortunately the reading will still need to do ourselves. Not trying to be snarky here, it happens to me all the time that I have not read something and complain it's hard to understand.
I think what OP means is that having good documentation should not require you to read a blog of any sorts, even if it is linked in the man page. Either documentation is good OR you read the blog, you cannot have both.
I disagree, for instance in a man page I don't want to read the rationale for something (which the blog provides), just the raw "if you do this, then that will happen".
That would have its place in a GNU info book instead.
It's open source, you get what you pay for. Actually, you get much more, but you need to fill any gaps with your own efforts. Accessing the spread out documentation is one of them.
While they are not comparable entities I'd say systemd documentation is in better shape than Linux kernel documentation. (Not to negate the efforts of those who do work with kernel documentation, but to stress the huge areas of no or pretty obsolete documentation).
Of course you can buy Linux (incl. user space) from the commercial players. I have only worked in one small project in my career that did, but I did not notice that better documentation was worth paying for.
> My take is that pay vs free software and good vs bad documentation are orthogonal and you can be in any of the four quadrants.
It's definitely not independent. Few people enjoy writing documentation and even then, it takes a lot of time. Plus, writing good documentation is something you need to train for. Very few OS people want to spend their free time writing code and then spend just as much again for - usually boring - documentation and support tasks.
Companies have exactly the same problem, but they have the option to throw money at the problem. Sure, there are some OS projects with good documentation (usually sponsored by a company) and a lot of proprietary stuff without, but proprietary software usually has more financial backing and that's directly related to good documentation.
I did not say that every open source project produces insufficient documentation. But some central ones that are hard to avoid do. There complaining doesn't help, you just need to invest your efforts. Ideally you could contribute better documentation, but at least you have to make the effort to learn it for yourself.
“Start with” the “blog”?
Clearly, the two does not connect well … for systemd.