I'm sure you've all seen the new NSHipster site that launched this week, No overview available. It's a survey of the state of the Apple framework documentation. Specifically, it shows stats on the number of undocumented symbols in each framework.

The community reaction to the site has been strongly negative, and very loud. As Mattt said when he launched it, poor documentation coverage is widely cited as a major problem, and this site is easy to point at and say "Look… I told you so!"

The number of documented symbols is certainly one aspect of complete documentation, but it's never as simple as a single, flawed metric. Why flawed? Is this any better than "No overview available"?

What's very surprising though is how loud people are shouting about this when lots of the percentages on the site are high! UIKit, by far the biggest framework with over 13,000 symbols is more than 90% documented! That's amazing. Yes, some frameworks are nowhere near 90% (the audio frameworks seem to be particularly weak spots) but it's not as bad as people are making it out to be.

Also, a single metric like this doesn't take into account all of the wonderful articles and sample code. They can be hard to find as they are scattered around the library, but there are lots of them and they are generally high quality. In my opinion, this type of documentation is even more important than the pure reference.

That brings me to what I believe the biggest problem with the documentation is, the amount of information that's no longer being updated in the archive. The old programming guides are wonderful, and many of the tech notes are invaluable. It's a tragedy to see them abandoned without being adequately replaced. It's a very sad situation.

We should be pushing Apple to focus on improving documentation and I'd love to see Apple resource this department with everything that it needs to get this colossal task done. It's just not as simple as aiming for 100% coverage.

Dave Verwer  





Business and Marketing


And finally...