This weekend, I spent about 4 hours trying to get a RewriteRule working. I did that because it’s somewhat cryptic, in the docs, why it’s so hard to do what I wanted to do. Or, more specifically, why it is impossible, and what the workaround is. Granted, the information is there, if you know that’s what you’re looking for.
I did this as part of the book that I’m writing. Now, of course, I want to add the example to the documentation.
I’ve been having this internal debate for quite some time. When I enhance (or someone else enhances) the Apache documentation, this has a direct negative impact on my ability to sell books and/or training classes. When writing Apache Administrators Handbook, I spent almost as much time working on the docs as I did working on the book itself. As a consequence, there was rather less need to buy the book. It also led to at least one reviewer saying that the book read like it was copied from the docs. And, in a very real way, it was. Or the other way around, depending on your perspective.
So I have to wonder whether it really affects book sales when we make the docs so good. I have to assume that it does, I suppose. I’ve more than once joked that we should make the docs worse, so that I can make more money. I suppose there’s a reason that books on Java stuff are available in such numbers. π From the docs for some Java software projects (I’ll avoid naming any names, since I don’t feel like getting flamed just now) it’s relatively hard to figure out what the software even does, let alone how to use it.