I just came across this post on Slashdot on how to create good documentation.  This is a good guide.  Too often, documentation that exists out there is not particularly great, or good at showing you how to do something.  This is the reason that I created my D-Bus tutorial – and I hope that it’s been useful to people.  Similar to how Log4J2 didn’t have excellent documentation – it makes sense once you know how things work, but there isn’t a nice, low-knowledge way to go about this.  In fact, right in the documentation it says:

An understanding of how loggers work in Log4j is critical before trying to configure them. Please reference the Log4j architecture if more information is required. Trying to configure Log4j without understanding those concepts will lead to frustration.

…and that’s about the point at which my eyes glaze over.

I’m not saying that the Log4J2 documentation is horrible, but it could be better and somewhat more structured as Steve Losh said.