Back when Documentation was announced, we got this comment:
If SO became the #1 repository of easily-searchable examples by language, framework, etc. I would never look anywhere else. Yes, one can google "How do I do X in Y-language/Z-framework" and you might come up with a examples through SO (sometimes), blog sites, etc., but if you want to do something in a not-so-popular framework or language, who better to show you how than the experts. I support this fully, as 99% of the things I search for in terms of software development are examples. Yes, I know how to read the Oracle Java Documentation, but that takes so frigging long. – Chris Cirefice
I love that because it matches the motivations that led us to pursue Documentation in the first place. To pick on Java for a bit more, I'm interested in functional programming and the Introduction to Java lambdas example caught my eye. It's a bit longer than needed, perhaps, but it's got nothing on this monstrosity I found via Google. Or maybe you prefer a Quick Start which advertises a completion time of: "Approximately 1 hour"? I'm sure those are great resources, but they don't work for the main thing I typically need documentation for: getting a quick overview or reminder of a language feature.
Documentation's primary navigation is search. That implies:
- Topics that get to the point quickly
- Self-contained examples
- Links that never rot
- Crosslinking encouraged
It's a bit too early to know if navigation-via-Google will work since there's not a lot of content for Google to index just yet. So we are stuck with tag Documentation consisting of long lists of topics holding potentially long lists of examples. Just like the early days of Q&A where some questions had dozens of answers, the whole system seems unwieldy and awkward. Hence, the request for structure.
One of my all-time favorite manuals is The TeXbook. It's a pleasure to read and carefully organized. Chapters introduce concepts in logical order. Examples and exercises are sprinkled in at just the right rate. Jokes are well timed. Nothing, not even a single character, is out of place. Stack Overflow Documentation can't compete with documentation authored by brilliant teachers. Instead, we should focus on what collaborative curation does best.
While it's not perfect, the pin-and-score system of Q&A bubbles up the most useful answers as reckoned by the asker and the community. Documentation borrows that system, but I think we can do better. Votes are not direct measures of an answer's usefulness, but an estimate based on the reader's instinct. It's not uncommon for me to find a question via search and upvote a handful of answers even though I only chose one to implement in my code. On the other hand, there are answers that have been viewed by thousands of anonymous users (who were likely helped) but only get a handful of votes.
But with Documentation, we can observe usefulness directly by looking at how it's are used in answers. In my opinion, Topics and Examples should be sorted as a function of the frequency of their citation. This isn't a new idea exactly. Citations are used to measure the impact of academic papers and PageRank provides a rough estimate of the imporance of a website. The most-cited examples will also tend to be the most widely useful.
So far there isn't much data about citation because they weren't available before public beta. But once we do have sufficient data, I'd like to see citations included as a metric alongside score and possibly replacing it as a default sort.