I was kind of vague on the qooxdoo framework in the original post, so I put in some more details about why I thought it was nice. I had a small conversation outside of the blog with Andreas. It was interesting to formalize why I thought that it was an appealingly documented framework. I learned a lot. I would say that there are likely objective criteria, and you can probably measure your success at least partially by metrics (how many downloads, new users, questions asked, etc.) It was interesting how the most used pages were the best, in that poor sentences were likely selected against. I think there’s an interesting thought around here with evolution of documentation. Kind of like forces tend to make documentation smoother in the spots where it is rough, like a river.

John:
I agree that PHP’s documentation was helpful when I worked with it. I liked the format of

1) very general description
2) method signature
3) argument explanation
4) detailed examples
5) user thoughts/suggestions

To my memory, a lot of times the user comments were helpful because they said something like, “don’t do it this way because this is insecure.” As of yet, I don’t know of a single place that you can look for documentation, it seems like it varies. I smell an opportunity. One thing that would be helpful is just to get some consistency. I mean, Java documentation typically looks very much different from .net documentation. If you know where something is and where to look for it, that can be quite helpful. Although to be fair, perhaps the kind of documentation that works for Java won’t work for Ruby on Rails, and vice versa. Perhaps it comes down to knowing your audience? (as writing should)

To Paul:
Glad that you agree. What better way to practice your skills in communicating and writing than working on something you find enjoyable and challenging? I think that the Pragmatic Programmers to some degree are doing this with languages like Clojure, Ruby on Rails, etc. They try to find a new shiny thing (language/framework/tool) and then make a book like people are used to seeing. This definitely helps popularize the shiny thing.

I concur that doing a test run or gauging the popularity is important if you want to make sure your efforts are useful. It seems like some of the Perl books are just formalizations of FAQs that are out there, but perhaps that only seemed to be the case because I was reading it after the FAQs and the books had coalesced on subject matter.

Of course, for the sake of the environment, think about eBooks or PDFs! Plus, you’ll probably get more margin by doing this due to less overhead of printing.

Thanks again for the comments guys, they were very thoughtful.

It would fulfill a need (for the information) and help the writer gain recognition.

Just creating a simple site with Docbook -> HTML would get huge amounts of traffic. The writer could earn a significant amount from ads and anything that gets a lot of traction could get published on paper. It would have a demonstrated audience.

With php.net you type in php.net/function_name and it will give you documentation on that function, documentation on related functions, user comments, caveats, etc.

It’s awesome. I wish JavaScript, C++, Perl, Python, Java, and all the other languages had this sort of thing. If you know of a similar site for other languages, can you share it??

Referring to qooxdoo as one of your “favorite examples of excellent open source documentation” came as quite a surprise. We usually tend to think there’s still tons to add, fix and polish. Thanks anyway, I believe your statement does indeed motivate us to further improve documentation.