Stackoverflow takes on documentation.

Simply put I love stackoverflow.com [SO]. An obvious statement from a developer, but I really love everything about it.

I love the guys that created it, the reasons they did and the way they went about it. I love how well it works. I love the awesomely named, Area51 and the communities it spawned.

I fucking love the points man.

Which meant I was pretty excited to finally hear about the beta release of SO's latest offerings, http://docs-beta.stackexchange.com/.

Below I give a brief description and try it first hand.

Documentation hasn't moved on

The developer community has long known that documentation is never perfect or reliable. Since there is no incentive to maintain documentation as a code base grows, an API's documentation quickly becomes spotty, uninformative or non existent.

The SO community think that they can use their extremely very successful system to create meaningful, rich and informative documentation.

Using those damned points and badges they are trying to get trick the developer community to write clear, informative and modern documentation.

How

Rather than dryly adding wordage for each API, library by library, documentation is written based on a topic with worked examples to give developers the right information to use the API.

A typical iOS topic could be NSThread with examples given such as

  • Run a thread in the background
  • Run two threads synchronously etc

Each topic may come with a formalization of the parameters as well as remarks on usage, pitfalls and other bits of information.

I've given it a bash with the Apple classic Reachability here.

Near future

Beyond documentation, I see that at some point, this site will become the defacto destination common code snippets.

There will be far few developers punching in the same old search term, just so they can find that one SO answer with the code snippet they need.

I am looking at you "how to dispatch a block once on main thread"!