Documentation!

Yes. He did. I have read it many a time, along with its companion ip-tunnels.tex. However iproute has two main commands: ip and tc. ip-cref.tex and ip-tunnels.txt only cover ip. I have no problem with either of them, other than perhaps him not providing them in the form of a man page.

But ip is a relatively simple command compared to tc, and all he provided for it was README.iproute2+tc. I guess without it, I would not have known the purpose of the tc command. For the rest I had to read the source.

> That said, I'd be happy to write a HOWTO for nftables

Bugger future messes these people might create, how about fixing the ones they have left behind? I wrote my own doco when I decided to use tc in anger: http://www.stuart.id.au/russell/files/tc/doc so I am not asking for someone to do something I haven't done myself. And before you ask the obvious question: after dealing with the kernel devs once, I think Conroy must be easier to deal with. Perhaps I exaggerate, but only by a tiny bit.

pdf and man-generation from docbook source are integrated and I even already wrote a few lines :) While I'm not good at writing HOWTO's, I intend to write command reference, syntax etc. documentation.

I'm trying to use nftables now ... in 2014. How about that HOWTO?

> I never fault the person who made the code available to me.

There is no doubt in this case I _am_ faulting the person who provided the code. Well, to be more accurate, I fault the project. The project should not accept the code without documentation.

Evidently you think this is unreasonable. But my attitude is actually worse, if that is possible - I hold different projects to different standards. I am perfectly happy with a buggy, poorly documented 1000 line utility I found on sourceforge. Yet when it comes to large projects like samba, apache and gcc I expect so much more. I actually expect code and documentation that is at least as good as I get from a commercial vendor. Can you believe that! I actually expect the open source process to produce a better quality product than something I pay money for!

Well unreasonable or not, I write the occasional open source program and I hold myself to those standards. You sort of have to really, because if you produce crap everyone can see it - you ain't some anonymous coder hiding behind an organisation.

Still, I don't produce code as good as I see in the kernel. Patrick, rusty and friends - they hold each other to the highest standards. New code that makes it into the kernel core is usually beautifully written. And the kernel project has a savage review process that ensures it stays that way.

Yet no matter how beautiful the code is, there is no point it if nobody uses it. And that is the situation netfilter finds itself in. Out of all the potential uses it might have it is deployed in, it is in but a fraction of them. This is because figuring out how to use it is a huge effort. Because there is no doco you have to read the source to get a true understanding of how it works. Thus only C programmers who are prepared to troll the kernel and iproute2 source really have a clue. Actually it is even worse than that. In the case of the schedulers the code is (necessarily) so complex the code only gets you part way there. You have to read the original academic papers on the algorithms used. (HTB, being the only scheduler written outside of the kernel team, is the one exception.) The situation is so bad its even defeated all the book writers.

So, returning to the original point, we have arguably the largest open source project of them all, the kernel, churning out code almost no one uses because they don't regard documentation as an important part of the final product. And yeah, I think this means the kernel development process is broken. And yes, I hold the people who drive that development process accountable. They could do so much better.