103

I have gone through some posts about Stack Overflow Documentation (1, 2, 3), and I haven't found a clear, simple answer to the question: do we really need it?

As I see it, there are currently (at least) three levels of information that you can use for improving your knowledge of a given programming language:

  1. Official documentation. Most programming languages come with pretty good official documentation. I include here well-known books on the subject.
  2. Canonical questions and answers in Stack Overflow. These questions deal with general topics that pop up often, and typically appear in the "frequent" tab.
  3. Specific questions and answers in Stack Overflow. These are the most common ones: someone asks, people answer, and others will use that knowledge in the future.

Doesn't Stack Overflow Documentation significantly overlap with items 1 and 2? Having official documentation for a language, do we really need Stack Overflow Documentation for that language?

Some potential answers are:

  • Stack Overflow Documentation is indeed much like 1, but the purpose is to make documentation easier to digest. Perhaps official documentation tends to be harsh or hard to follow? In my experience it's exactly the opposite, but my experience is quite limited.
  • Maybe my premise 1 is wrong, and some languages lack documentation, or have very bad documentation. Again, that's not the case in my experience, but then I only know a few languages.
  • Perhaps Stack Overflow Documentation does fill a hole that is not covered by 1, 2 or 3 above, and I simply fail to see that hole?
8
  • 4
    Related: What, exactly, is Documentation? Jul 28, 2016 at 11:19
  • 2
    @Bjørn-RogerKringsjå Thanks for pointing out that question. Mine is more how does SO doc differ from official doc. I have edited to make that clearer
    – Luis Mendo
    Jul 28, 2016 at 11:22
  • 6
  • 14
    I'm looking through example after example and I cannot even believe people are wasting their time putting in so much information that is so useless. I ran into one regarding opengl that was nothing but utter nonsense, and it was I kid you not pages and pages long...and guess what...hardly anyone is going to read that stuff.
    – JonH
    Jul 28, 2016 at 16:51
  • 9
    @JonH Exactly. When there's such good official documentation, what's the purpose of having non-official documentation? And you've hit the nail with that other important issue: who will read the documentation? If they read the official one in the first place, the number of questions in SO would be much lower :-)
    – Luis Mendo
    Jul 28, 2016 at 16:54
  • 16
    @LuisMendo To answer your question absolutely no one because it's all garbage so far. Nothing in it makes sense, its not ordered correctly, in fact I cannot for the life of me figure out how any of this structures out correctly. Immediately when I go to a topic I am presented with examples without a clear indication what the language does, what methods are available and what parameters are being passed. After reading one nonsense example I scrolled down to read an entire section about Hello World...scrolled down to another example only to learn that the first topic was conflicting.
    – JonH
    Jul 28, 2016 at 16:57
  • 1
    @JonH "...hardly anyone is going to read that stuff." If the structure gets better and if the examples get better, why not? I will wait a few month more and will judge then how useful the whole thing will be. Jul 29, 2016 at 9:20
  • 6
    It's peanut butter. Jul 29, 2016 at 16:48

5 Answers 5

50

In general: SO Documentation is supposed to be a source of examples of how to achieve specific things in a said technology.

What we usually see in official documentation is a list of APIs without any explanation of how they are supposed to be used, how to achieve specific goals using them or any examples of usage.

The idea is to complement and enhance such official documentation.

20
  • 5
    Thanks. In my limited experience (mainly MATLAB) official doc is not like you described in the second paragraph. It is quite good, with explanations and examples.
    – Luis Mendo
    Jul 28, 2016 at 11:52
  • 7
    @LuisMendo - that's a fair comment. SO Documentation is not meant to replace official documentation, but supplement it where needed. Not all official documentation sucks, but much of it does.
    – Oded
    Jul 28, 2016 at 11:54
  • 3
    So, assuming the official doc is good, would it be better to use SO Documentation or "canonical" self-answered questions to address commonly found issues?
    – Luis Mendo
    Jul 28, 2016 at 11:59
  • 2
    @LuisMendo - If the core of the issue is in usage and the current documentation doesn't have a good clear example, possibly documentation is a good place for it (i.e. library documentation), if it is beyond that possibly a question/answer.
    – Oded
    Jul 28, 2016 at 12:02
  • 40
    It seems that one problem is that most topic requests here on Documentation are answered well by the existing documentation. Why do people request such topics then? Should we have a "Is documented well elsewhere" decline reason? Jul 28, 2016 at 15:55
  • 2
    This should be included in a description somewhere. It finally clarifies what the purpose of Documentation is for me. Jul 28, 2016 at 16:24
  • 6
    @Trilarion "Why do people request such topics then?" Because, just like the thousands of people who ask trivial questions on SO every day, they don't read the official documentation. They probably don't even know it exists, since they've spent their entire programming careers being spoon-fed tailored answers on SO. Docs.SO won't change that; people who don't read well-written official documentation won't read well-written unofficial documentation, either. The goal of Docs.SO should be to step in where the existing documentation sucks. Jul 28, 2016 at 16:32
  • 21
    If this is what documentation is for, wouldn't a bunch of self-answered "How do I do X with technology Y?" questions do the job better?
    – Mark Amery
    Jul 28, 2016 at 16:33
  • 46
    IMO a) "documentation" is a pretty bad name for "examples of how to achieve specific things" and b) encouraging people to just copy-paste examples (who probably won't follow the license terms) doesn't sound great either. If I'm ever looking for an example, rather than trying to understand some technology feature, I usually find a perfect SO Q&A for it already.
    – OrangeDog
    Jul 28, 2016 at 16:59
  • 4
    I think the most useful examples are when two different technology are used, as the official documentation hardly every gives good example of using other technology. Most of the current examples seem to be covered better is existing documentation, or blog postings. It seem that people are just writing examples for the sake of it, partly due to it being new, and party to get rep. Jul 28, 2016 at 17:01
  • 11
    This is exactly how I personally like to envision Documentation: as a repository of examples, debugging checklists, and such, the stuff that sometimes comprises the comment section in official documentations. Real world info by real world people, well organized using a top-notch editing system (which I have no doubt Documentation will become), as opposed to the abstract official docs. But as others have said already, what we're currently seeing happening is often duplication of existing documentation. (cont'd...)
    – Pekka
    Jul 28, 2016 at 18:23
  • 1
    (...cont'd) Which may be unavoidable in the long run - perhaps SO Documentation can work only if it eats all other Documentations. But that's a big goal, and it's causing understandable friction with those professionals who create and use the official docs.
    – Pekka
    Jul 28, 2016 at 18:23
  • 5
    @Pekka웃 yet the Q&A format is already well-suited both to examples (which would be much better as self-answered 'How do I do/use X?' questions, where competition between approaches can occur and example don't risk being nuked by another editor) and even debugging checklists - see programmers.stackexchange.com/questions/46716/… for a great example. A change to the rules to tentatively encourage such Community Wiki questions would do more good towards your goals than the entire documentation site.
    – Mark Amery
    Jul 29, 2016 at 16:10
  • 2
    @CWilson these are my impressions from seeing things on the inside, from what I understood the goals of documentation to be. So, I guess, not "official", as such.
    – Oded
    Jul 29, 2016 at 16:26
  • 6
    If this answer is in fact official, or at least accurate, I find it unfortunate: not that something like this shouldn't be in SO/SE (not my call), but that the name and the official published information about this new tool do not in fact explain this. I have found many meta posts that describe this as a 'cookbook' or 'how to guide', but none official, and my reading of the official sources (perhaps flawed, but I am obviously not alone) seem to indicate otherwise. Perhaps this answer could be added to the documentation tour, and some of the consternation voiced in Meta would cease?
    – CWilson
    Jul 29, 2016 at 16:29
2

To answer your question simply: who writes it.

Which sounds trivial, but I believe it may be the greatest strength to SO Documentation.

Official documentation is written by the same people who wrote the content that is being documented. Being so familiar with the material, or "down in the trenches" as it were, gives these writers a very different perspective from the user base. This difference in perspective translates into a difference in understanding that can make official documentation confusing, especially to individuals who are brand new to the material.

SO Documentation is/will be written by users of the technology, and will therefore be lacking any biases that the creators may have had. In theory, this will make it much more approachable, especially to new users, to whom documentation is the most important anyways.

7
  • 11
    That pretty much ignores, that documentation should be (and often is) authored by technical writers, based on the specification they have. Jul 28, 2016 at 17:38
  • @IInspectable: You mean coders are writing some kind of Documentation called "specs" beside their actual implementation, and that other people called "technical writers" write Documentation based on specs. Wait! Or maybe I got it wrong. Analists/Chief Architect/Smartasses write specs, then two kind of dumbasses "programmers" and "technical writers" separately write "implementation" and "documentation". rotfl
    – kriss
    Jul 29, 2016 at 10:00
  • @kriss: You are right about one thing: Irrespective of how you go about writing specifications and documentation, it takes good personnel to get it right. From the sounds of it you haven't been fortunate enough to work at a place, where this is the case. Jul 29, 2016 at 10:05
  • @IInspectable: actually I fled places where it was the case. Going Agile and replacing formal specs by working automated tests and autogenerated reference documentation (typed by developpers and extracted from source by automated tools) was also a great relief. And all this was a great relief, a huge time saving and significant improvement in quality. Competent people may indeed reduce damages, but its better yet to fix the process. Then the same competent people can do even better.
    – kriss
    Jul 29, 2016 at 10:15
  • 6
    Users are in the absolute worst position to document systems that they use. By definition. This is nonsense! Jul 29, 2016 at 16:50
  • 2
    @LightnessRacesinOrbit: I wouldn't say the "worst possible position". The writers of a lot of systems don't eat their own dog food, so they often misunderstand where the difficult-to-understand parts are in their systems. This leads to spending more words on trivial matters than on the things that are actually hard to understand. Now that being said, they can often make up for that with their comprehensive knowledge of the system, which allows for greater depth than most mere users can achieve. Jul 30, 2016 at 5:45
  • 4
    @NicolBolas: Users can only make assumptions about the various preconditions and postconditions. Oftentimes those assumptions are wrong. Users should instead read the documentation to determine how the code is supposed to be used. If they're also the ones writing the documentation, that is broken. Jul 30, 2016 at 12:28
1

I think the benefit of SO Documentation is the ability for it to be community generated and improved upon constantly. (As opposed to something like Javadocs which is made by the developer and then you either like it or you don't.)

The benefit of such documentation is that it can do a better job of explaining things in laymans terms, whereas official documentation tends to be more technical. The method of providing documentation through example rather than plain explanation supports this.

In the future it can also be a good resource for libraries with little or no documentation at all. Open source projects or even the companies themselves could use it to provide documentation for their product/program and it can be supplemented with help from the community that uses it.

EDIT:
In response to why things need to be explained in "layman's terms":

As Jakub Lokša mentioned there are many non veteran programmers that use this site as well. Consider the following explanation in the Javadoc for the LinkedList class:

Note that this implementation is not synchronized. If multiple threads access a linked list concurrently, and at least one of the threads modifies the list structurally, it must be synchronized externally. (A structural modification is any operation that adds or deletes one or more elements; merely setting the value of an element is not a structural modification.) This is typically accomplished by synchronizing on some object that naturally encapsulates the list. If no such object exists, the list should be "wrapped" using the Collections.synchronizedList method. This is best done at creation time, to prevent accidental unsynchronized access to the list:

There are many terms in there that would be entirely foreign to someone in their first year or two of programming that they likely wouldn't care about (ex. synchronized, Collection, concurrently, multiple threads etc.), but would confuse them. You might say they should just skip them and they probably would, but they would be left feeling like they don't understand the topic at all.

The documentation on SO is a great resource for those starting out (and for those who get confused by technical explanations). We all learn things differently and SO Documentation helps provide an alternative.

An additional benefit I didn't mention before is that over time this could potentially lower the number of basic (and/or duplicate) questions being asked on simple topics. SO could potentially have a popup saying that documentation has an example on the topic they are asking a question about so that perhaps the questioner would be able to look it up themselves.

9
  • even the companies themselves could use it to provide documentation Perhaps you should mention that/if the default license of SO Documentation permits it? (I don't know about that, I'm just pointing out a possible issue)
    – Luis Mendo
    Jul 28, 2016 at 17:31
  • 7
    Why do we need to explain programming APIs in "layman's terms"? Jul 28, 2016 at 22:30
  • Companies have realized that. For example docs.microsoft.com/en-us can be edited by everyone. Being able to incorporate feedback from users is a great advantage. Not every official documentation has simple ways for that yet. However, even then it might be good to have an alternative voice to the official documentation - just to have some choice. Jul 29, 2016 at 9:27
  • Not everyone reading StackOverflow is a professional programmer with 10+ years of experience. It's much better for a beginner in programming to see examples explain in "layman's terms" as opposed to unnecessarily complicated technical terms, which only experienced programmers understand, and confuse beginners. I think seeing a documentation which beginners don't understand just contributes to new users spamming simple questions on SO. Just my 2 cents. @CodyGray Jul 29, 2016 at 10:08
  • 5
    "You might say they should just skip them and they probably would, but they would be left feeling like they don't understand the topic at all." Tough. That paragraph includes vital information, and documentation which does not include that information is horribly incomplete. Jul 29, 2016 at 14:04
  • @NicolBolas It is only vital information for a more advanced programmer. You don't teach a new programmer about design patterns because they need to learn the basics first. You also don't confuse them with technical jargon that they don't need and won't understand. With SO Documentation there can be one example that deals with the basics of a LinkedList and another that goes into the issues dealing with synchronization and concurrency. The documentation shouldn't be incomplete, but it can be divided in ways that make it easy for people on many different levels to understand.
    – yitzih
    Jul 29, 2016 at 14:21
  • 5
    @yitzih: And if Docs.SO had some form of order to it, I would agree. But it doesn't. There's no guarantee that a user will land on the LinkedList example or the synchronization-with-LinkedList example first. There's no expectation that a user doing threading will have read the warning about LinkedLists in the synchronization topic. And so forth. Jul 29, 2016 at 14:23
  • 3
    I'm not a professional programmer (though I'm open to the opportunity :-), nor do I have anything approaching 10+ years of experience. I program for fun, as a hobby. Still, I don't understand how it's desirable to read documentation for programming APIs that is written in layman's terms. Programmers writing code to consume the APIs are not, by definition, laymen. They need to understand the design in detail, not just copy and paste code they don't fully understand. Sure, programming is hard; it takes a while for beginners to get up to speed. But ignoring the reality creates far more problems. Jul 30, 2016 at 14:22
  • @CodyGray I'd still appreciate to read something in layman's terms when I'm reading a subject I'm new to. That doesn't happen often, nor is it a good reason for everybody doing it. But a middle ground can benefit most people, if it doesn't patronize the reader and is accompanied by accurate and in-depth information.
    – Fabio
    Jul 31, 2016 at 13:24
-6

In my experience, documentation quality varies widely. Some companies/organizations provide excellent documentation for their products or languages. PHP, Python, C# all have great documentation -- lists of methods and examples of usage. PHP docs are especially good at this with user added content.

In these cases many more examples of usage are necessary. If documentation were much better, there would not be nearly as many questions/forums/blogs etc. because people would know how to use the classes and methods. I can search for hours trying to find out how to use a simple function. That time could have been reduced to a few minutes if the documentation had provided the function definition, argument types, return type and sample usage.

On the dark side of documentation, there are languages and highly used libraries that have poor to non-existent docs. Adobe has great documentation on Photoshop, but they always had extremely lacking documentation on ActionScript. Thankfully ActionScript is going away.

1) The Pandas library in Python needs considerably more documentation, especially examples.
2) Apache Spark documentation is horrible. Lots of functions, little to no explanation of how to use them. When examples are provided, you get to see how 2 of the 20 arguments are used.

I could name many more, but examples are ubiquitous.

What about bugs in languages? They're never included in the docs. I could envision SO Docs including (officially recognized) bugs in the doc pages and potential workarounds. Official docs often don't refer to libraries, but libraries are vital for many uses, so a one-stop-shop (a.k.a. Amazon) approach is definitely needed.

I would love to see SO documentation be sort of the Wikipedia of the field. Explanations and Examples should be well organized and easy to follow. If this happens, I'll be using it constantly.

11
  • 17
    "If documentation were much better, there would not be nearly as many questions/forums/blogs etc. because people would know how to use the classes and methods." hah. hahaha. hahahaha. no.
    – Kevin B
    Jul 28, 2016 at 18:11
  • 1
    I have proof. All you have is an opinion.
    – HonestMath
    Jul 28, 2016 at 18:12
  • 10
    @Matt the existence of the phrases RTFM and LMGTFY and the consistent need to apply them both are Kevin B's proof.
    – Jeutnarg
    Jul 28, 2016 at 18:17
  • 5
    Every jquery method is thoroughly documented and has a working example. We also have the learning resource learn.jquery.com, and the majority of jquery questions that reach SO are already answered through the documentation or the learning resource. and yet, we have received nearly 500 questions in the past 24 hours tagged jquery out of 10k or so. that's 1 out of every 20 questions asked. (sorry for the napkin math)
    – Kevin B
    Jul 28, 2016 at 18:22
  • The official docs can't possibly have an example for every possible way of using jquery, that's where SO docs come in.
    – Kevin B
    Jul 28, 2016 at 18:24
  • 5
    Matt, your "proof" isn't very good. You say in your answer here that C# has "great documentation", yet there are probably more questions asked about C# on Stack Overflow than any other single technology. So what exactly is the evidence you're providing that "If documentation were much better, there would not be nearly as many questions/forums/blogs etc. because people would know how to use the classes and methods"? (Coincidentally, the C# Documentation.SO is terrible, quite inferior to the MSDN documentation, and I suspect that will be a brand new source of questions.) Jul 28, 2016 at 22:29
  • I actually agree with Matt. Instead of spoon-feeding people on the Q&A site, it's much better to give them more general examples. This is far less effort from the contributing side, than answering the same useless questions over and over again. Jul 29, 2016 at 9:24
  • 3
    @Trilarion: But those questions are still going to be asked. Why? Because the people who ask them don't read documentation at all. They don't search for answers themselves; they just ask us to search for them. Jul 29, 2016 at 14:05
  • @NicolBolas That's true. But we aren't obliged to answer. Or at least we could then refer to Documentation. (RTFM close reason). Jul 29, 2016 at 14:14
  • 3
    @Trilarion: That just trades the current RTFDuplicate problem for RTFM problem. That's not fixing a problem; it's just changing how it manifests. Jul 29, 2016 at 14:16
  • @NicolBolas You're right. In the last days I also thought about the very big overlap between Q&A and Documentation and I wondered if we really need Documentation. But still increasing the distance between questions and answers a bit and starting with the general notion that the answer already exists (somewhere in the manuals), you just have to find it, seems like a good idea to me. I would rather have the RTFM problem than the RTFDuplicate problem. It seems to be more general to me. Jul 29, 2016 at 14:40
-6

How does Stack Overflow Documentation differ from official documentation?

Let's do some math:

The best documentation you ever read - official documentation = Stack Overflow Documentation

That's at least my vision of how Docs.SO should look like.

do we really need it?

If "the best documentation you ever read = official documentation", no.

Having official documentation for a language, do we really need Stack Overflow Documentation for that language?

See above.

Perhaps Stack Overflow Documentation does fill a hole that is not covered by 1, 2 or 3 above, and I simply fail to see that hole?

Maybe you don't see that hole because for you that hole doesn't exist, since the documentation you use is probably that good. Also see answer #2.

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