12

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:

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.

6
  • 5
    Personally I think Documentation would grow quite well organically without voting rep and only as an aside to Q/A. I can think of lots of repeated situations from my years of answers that when encountered again would be well served by sticking an example in Documentation that fits a real need, not because some student looking for rep thinks it might fit a need but in reality can be found easily with a bit of searching. Organic Q/A driven growth will be slower but percentage of actual examples cited within would be significantly higher.
    – charlietfl
    Commented Jul 25, 2016 at 20:21
  • 1
    My concern about this is that many of these so-called "citations" are really just "See also: RTFM" appended to an answer as an after-thought. That doesn't really speak to the quality or usefulness of the linked documentation. Worse, we have active incentives for people to add links to Documentation (the awarding of badges and, currently, the possibility of reputation if you contributed to the Doc), so this is not a pure metric. You allude to how citation frequently is used in academia, but I don't see anything analogous here. PageRank is more similar, but then why limit it to internal links?
    – Cody Gray Mod
    Commented Jul 25, 2016 at 23:24
  • 1
    @CodyGray: Citation impact is hardly a pure metric in academia. As the Wikipedia article notes, review papers are more frequently cited. Wikipedia itself gets undue benefit from PageRank since people often link to it a good place to start. That's not a flaw necessarily.
    – Jon Ericson Staff
    Commented Jul 25, 2016 at 23:32
  • I like that you can include citations in SO questions/answers and I really like that there is an icon that accompanies the citation to differentiate it from other links. But after following some citations I wondered if using them may have a negative effect on a question/answer. For instance this answer has 3 citations, following the first shows a message box stating "Linked example has been moved; view prior to move.". The second is fine (for now) but the third has an "Improvements requested by [...]:" box ... Commented Jul 26, 2016 at 0:03
  • ... and after reading the requested improvements your left wondering if the example is correct as-is or if the person requesting improvements knows what they're talking about. This will probably change and hopefully get better as the beta progresses, but I currently don't want to include dead links or a link to unclear/conflicting information in a question/answer. Commented Jul 26, 2016 at 0:03
  • Maybe we could also use visitor impressions as usefulness measure of a Documentation page. Commented Jul 26, 2016 at 9:07

1 Answer 1

4

Using a feature to support the citation of examples could be an approach which would also allow you to distinguish how many questions caused examples to be upvoted as well as the amount of times examples solved a question's problem.

One option to make use of the extensive example set in Documentation would be to allow questions to be closed as "documented".

enter image description here

The documented at... option could open a very similar interface that duplicate of already uses, except it would only search examples. It could be facilitated similarly to the way that duplicate closure works with regards to 5 votes (or 1 hammer).

Upon closing, the example is then placed as the answer in full, along with its live vote count, and any upvotes on the example there will cause it to be +1 along with the correlated example reputation (+5 not +10).

This should not only drive more traffic to quality examples on Documentation, but should also help users solve their problems quicker by getting to more in depth in formation faster. While one user may be the fastest gun in the west to hammering out a small answer, an example curated by dozens of users will easily outweigh the value to the OP.

5
  • Would this mean we need to be able to make examples that are referenced by questions impossible to delete?
    – Kevin B
    Commented Jul 26, 2016 at 22:24
  • @KevinB - That is the way duplicate posts work as well, so I would assume so. I am sure if there were problems a moderator could fix something like that, it doesn't seem like it would happen much at all - for a legitimate example to be useful enough as an answer only to be deleted. Was there something problematic from that angle that you had in mind?
    – Travis J
    Commented Jul 26, 2016 at 22:27
  • well, for example, there's quite a few examples within the jquery tag that are being deleted due to being better documented on official docs. however, most of those examples could likely be used to close quite a few existing jquery questions.... but they don't supplement the official documentation... seems like this would cause some examples to stay around just because they could be used to easily close questions, regardless of them actually being needed here.
    – Kevin B
    Commented Jul 26, 2016 at 22:28
  • I suppose it would depend on how ingrained the examples had become in posts. If the same example was an answer to dozens of posts, should those posts be removed? Merged? A community wiki and a group duplicate closure? Perhaps all closed questions are reopened and the example deleted? It is hard to tell at this point. Perhaps the example is soft deleted from documents and just remains as the accepted answer where it was already set.
    – Travis J
    Commented Jul 26, 2016 at 22:33
  • Overall I think what you are describing would be a small edge case.
    – Travis J
    Commented Jul 26, 2016 at 22:34

Not the answer you're looking for? Browse other questions tagged .