Skip to main content
added 71 characters in body
Source Link
BoltClock Mod
  • 722.1k
  • 38
  • 431
  • 392

Peer review on Docs.SO? Complete and utter failure. The fact that it takes just any 4 people who lack specific domain knowledgeindividuals to allow anything on the site, even when none of them has the specific domain knowledge or is otherwise a suitable reviewer, shows the failure of this system. This is a non-trivial part of the lack of quality of Docs.SO.

Peer review on Docs.SO? Complete and utter failure. The fact that it takes just 4 people who lack specific domain knowledge to allow anything on the site shows the failure of this system. This is a non-trivial part of the lack of quality of Docs.SO.

Peer review on Docs.SO? Complete and utter failure. The fact that it takes just any 4 individuals to allow anything on the site, even when none of them has the specific domain knowledge or is otherwise a suitable reviewer, shows the failure of this system. This is a non-trivial part of the lack of quality of Docs.SO.

We don't call people "idiots" because that's a violation of one of the core principles this community is built on. (For the record, "intellectually challenged" is no better.) Hat tip, Cody Grey.
Source Link
Jon Ericson Staff
  • 21.5k
  • 27
  • 153
  • 182

Peer review on Docs.SO? Complete and utter failure. The fact that it takes just 4 idiotspeople who lack specific domain knowledge to allow anything on the site shows the failure of this system. This is a non-trivial part of the lack of quality of Docs.SO.

Peer review on Docs.SO? Complete and utter failure. The fact that it takes just 4 idiots to allow anything on the site shows the failure of this system. This is a non-trivial part of the lack of quality of Docs.SO.

Peer review on Docs.SO? Complete and utter failure. The fact that it takes just 4 people who lack specific domain knowledge to allow anything on the site shows the failure of this system. This is a non-trivial part of the lack of quality of Docs.SO.

Source Link
Nicol Bolas
  • 471.9k
  • 61
  • 186
  • 279

How do you determine if it has failed? There are so many standards by which you could measure the current functionality of Docs.SO as a system.

So let us look at the foundation document for Docs.SO: Warlords of Documentation. It enumerates four broad problems with documentation, so let's see if we've succeeded at any of them:

  1. Documentation is often an afterthought, obviously done just to say that it exists, with little concern for its quality. We've all seen plenty of this in our time. We can bring a focus on quality, peer review, and "actually solves real problems for real developers"-ness to documentation that would be very welcome.

I would say that, objectively speaking, quality on Docs.SO is... scattershot. I'm sure there are some good examples out there, and even whole topics that are decent. But as a whole, I'd say that whatever quality is there is drowning under a tide of (at best) mediocrity. And plagiarism.

Peer review on Docs.SO? Complete and utter failure. The fact that it takes just 4 idiots to allow anything on the site shows the failure of this system. This is a non-trivial part of the lack of quality of Docs.SO.

As for solving "real problems for real developers"... I'd say that Docs.SO by and large doesn't do that. Topics tend to be more of the "basic documentation" variety rather than anything problem or task focused. As such, examples more often than not demonstrate how a tool works, not how you're supposed to use it to accomplish something useful.

So overall, #1 is a bust.

  1. Often documentation is lacking in examples, or the examples are trivial and don't demonstrate typical use. Because Stack Overflow benefits from constant feedback from developers writing real-world code, we could greatly improve the quantity and quality of examples. Let's be honest: finding examples is already a common use-case for Stack Overflow; we might as well embrace it.

Docs.SO is example-focused documentation. In a technical sense; the meat of topics are called examples.

However, most examples on Docs.SO are not "real-world code". They're artificial, used to explain a specific point. They show off how to use a method or a class or something of that sort. But very little of it is something from "real-world code".

So #2 doesn't seem to be any good either.

  1. Much of the documentation out there is tied to release cycles, and thus infrequently updated and rarely "complete". The community-contributed and edited nature of Stack Overflow would be an immediate improvement.

It's hard to evaluate how well Docs.SO handles being out of date. It does however acknowledge that versions are things that exists, and provides tools that allow users to add version-specific information.

However, considering the low participation in Docs.SO, it is highly unlikely that, as new releases of software are made, Docs.SO will be updated in anything like a comprehensive fashion. So as time passes, Docs.SO will become increasingly out-of-date.

This isn't a structural problem so much as a participation problem. If Docs.SO were actively maintained by a set of energetic and skilled hands, this would probably work out.

  1. A lot of documentation descends from Javadocs, and while it was better than nothing in '96, it's hard to call framesets with unshareable URLs "good" in 2015. We can focus on creating the best UX for creating and serving documentation on the modern web.

This is probably more subjective than most, but quite frankly, I'll take JavaDoc organization over Docs.SO any day of the week. Oh sure, you can link directly to an example, or to the syntax or remarks section. You can even link directly to a specific version, to ensure that you're showing off something that won't change.

But if you need to know what a function does, it's still a lot easier to find a JavaDoc page on it than the appropriate Docs.SO article. Docs.SO's search is horrible, which makes finding specific information essentially impossible. You can't just type in a class/function name and expect to find something on it.

JavaDoc may have terrible HTML, but if you know the class and member function that's causing a problem, you can at least find their crappy documentation about it. We can't even get that far.

So, is Docs.SO a failure? I would say that there's good evidence that it has yet to accomplish any of the stated goals of the project.