The personal writings of Dave Sanders, about politics, technology, programming, and geekdom.
I am starting to go through documentation to learn both a new programming language (Objective-C) and a new library or two (Cocos 2d and Chipmunk) and its been a lot of work. I appreciate that many different open source projects just don’t have the resources to devote to documentation, but its even more frustrating when they have at least put some time in it and the formatting is weird, or you can’t search a certain way and so on.
One project (which is open source and has a commercial product license) that DOES do documentation extremely well is ExtJS. They not only write very, very good documentation, often with examples and cross references, but they also use ExtJS to render the documents, making it appear more app-like in the browser. They have two different search features built right in (which hit their server for results), they include direct links to the source code, and they have innovative features like “Hide Inherited Members” which often lets you find things much more quickly on the classes. In my mind, they have the best documentation viewer I’ve seen in all of my programming years. Its complete, its fast, and its painfully simple - but it still looks good and acts well when you use it. In fact, it helped “sell” ExtJs to me as a technology because I could quickly get up to speed with it and could see it in action at the same time.
Over the years I’ve also used Microsoft’s MSDN documentation and for a long time it was really good. I could usually find what I needed quickly and your documentation library had EVERYTHING they made it in. However, since VS.Net came around and MSDN started trying to do this hybrid offline / online version, it never seems to work right for me anymore. Sure, I can configure it and sometimes get results, but most of the time its faster to just pop open google and find the results on their site. Which is great if I’m online at the time, but sucks if I’m not.
Furthermore, it seems that every site or project has a different method of handling their documentation. Some use doxygen, others javadoc, others just hand roll it in html and more. Other technologies don’t even have solid cohesive docs, but rely on their communities to post up information.
I would really like to see the following get built:
This, I think, nails the requirements: documentation can be easily made to be uniform, communities can help document open source projects in a meaningful way, and the end-user developer gets a great, modern and uniform method of learning new SDKs and frameworks. By being able to get great docs, the frameworks and projects benefit by having a larger and happier user base, less forum questions, and more acceptance of their products.
Oh, and all of the above should be open source, GPL, etc. But standardized! If someone comes up with a better viewer that conforms to the standard - great! (I personally would love to see an iPad version myself….)
Best of all, it would take a handful of talented developers just a couple weeks to get something like this off the ground. We’re not talking rocket science - just communication.
If you are interested in such an idea - twitter me @vulgrin. If you think its a good idea, but aren’t able to help - tell some of your developer friends who might have time. If we can get a group of like minded folks together on something like this, we could make it a reality pretty quickly.
Also, the code name I’ve come up for this is “Doxter.” Serial killer docs? :)
