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? :)
Speaking of kids, O has his last Derby Car race tonight! :( He’s about to graduate out of Cub Scouts and into Boy Scouts next month, so this is his last chance to race a car.
In years past, Dad has had to do a lot of the work. Usually due to time constraints or just technical difficulty, O would be the designer and grunt job worker (like sanding) and then I’d do a lot of the more technical work. This year he’s done almost everything by himself. I did a coat of paint and put in the wheels, which is always really tricky and easy to screw up. (I’ve screwed it up many, many times.)
This year, he went for a racing carrot. Will post pics later, along with pics of ALL of his cars over the years. It was a nice, simple design, but completely and entirely unique. I doubt anyone in a 50 mile radius has a racing carrot.
So, its his last race and as Cub Scouts wrap up, I’m getting a little verklempt. But, its time for him to move on up, and I don’t get a break. Next fall, J starts Tiger Scouts, and I get to do the whole thing all over again.
O has been taking piano for over three years now, and he’s doing a great job. K and J have also both started, and though K isn’t that thrilled with it, O and J are actually attacking it right now.
O especially has come “over the hump.” We’ve sort of forced him to keep piano up because we knew he had some natural talent. (He can pick things up and start playing them by ear very, very quickly.) The past year has been tough because he was busy, didn’t want to practice some of the time. But suddenly he’s really starting to get into it and be excited about it. Nice to see it starting to pay off for him.
Man I’ve been superdad the past couple days. Helped my daughter get some photos together for a school project. Cub scouts meeting. Helped my son with his derby car for cub scouts. All while working on FOUR (!!) different projects for work.
Can I have sleep now? Kthxbai
Really digging PolitiFact.com now. Its pretty funny seeing this page on Glenn “No Truths” Beck.
Heard about this on NPR. Even if you think that Obama has done nothing, and are angry about the Healthcare Debacle, he HAS been getting something done.
Far more than his predecessor who spent 96 days or so off at his ranch or Camp David that first year before September 11th.
The media seems shocked and / or jubilant about the results from Massachusetts this morning. Why?
To abuse a sports metaphor, Congress has taken the healthcare football that Obama threw to them and not only fumbled at the 50, but at the 40, the 30, the 20 and the 10. Then they sat on the field, took apart the stitching on the football, stuffed the thing with cash and prizes, and then did an endzone dance ten yards away from the actual goal line.
We need to just can the whole thing. If we’re not going to enact REAL health care reform, then don’t make it worse and act like you did something. Grow a pair, side with the people for once and actually tear down the system and rebuild it. Until profit is out of the system, the system will remain broken and we will always have the “have nots.” Which means, these lapdogs in Congress are going to have to turn around and bite their campaign finance masters.
Until then, all the “Yes we can” populism is just going to be so much shouting into the wind.
Trying out the iPhone tumblr app. Funny that iPhone dictionary really doesn’t want me to type “tumblr.”
Every year or so I get the blogging urge again. Since there are some interesting developments going on right now, in that I’m starting up a new company, I wanted to have a place to put down some thoughts and start linking to things I’m researching and learning about. Sometimes, Twitter just doesn’t cut it when you want to get something out. Life wasn’t meant to be described just in 140 character chunks.
So here I am.
