85

For many questions posted to Stack Overflow, the questioner could have solved the problem themselves in a few minutes of reading the documentation. However, much as the workings of a for loop seem so much more obvious to an experienced programmer, it occurs to me that the instinct to go for the manual and the knowledge of how to efficiently read it are not obvious and innate to all people.

How can we help people learn to RTFM? Beyond simply telling people to do it, what resources can we provide to teach them to do it? What kind of comments should we leave? Is it just something that needs practice before it becomes second nature, or are there specific documentation-locating and documentation-reading techniques we should point out? Is there a canonical question to link to (and if so, is it structured in a way that's useful to the people it targets)?

79
  • 53
    How about just answering the question? Maybe include in your answer an explanation of how you found the information—where you looked, what the relevant sections of the manual were, etc.
    – Cody Gray Mod
    Commented Jun 20, 2014 at 7:54
  • 47
    To learn how to answer questions, I suggest reading the help center.
    – BoltClock Mod
    Commented Jun 20, 2014 at 7:56
  • 5
    @BoltClock: I'm not seeing how that relates to the topic. If you're talking about how to answer other people's questions, that's not what this is about. If you're talking about how to answer your own questions, the help center doesn't seem to go into much more detail than "search first". Commented Jun 20, 2014 at 8:01
  • 43
    @user2357112: I was making a joke based off of Cody's comment about answering questions and the topic of RTFM in general. To be fair, it was a really bad joke.
    – BoltClock Mod
    Commented Jun 20, 2014 at 8:02
  • 10
    @user, sometimes we have to face the facts and realize some of these users cannot be helped. For instance, we have an <expletive> interstitial to guide new users when they post questions, yet we routinely deal with utter crap. Some people just don't read, be it the fine manual or anything else. Commented Jun 20, 2014 at 8:11
  • 35
    Really, though. I wouldn't be surprised if Stack Overflow assumed a user had manual-reading skills already. This is why downvotes are used to indicate lack of research effort. There is no need to invest resources in teaching someone something they're expected to know by the time they come here.
    – BoltClock Mod
    Commented Jun 20, 2014 at 8:14
  • 5
    Well yeah, I mean, I didn't say it would work. People who are unwilling to help themselves are generally unwilling to help themselves. You aren't going to teach someone how to help themselves if they are uninterested in learning it. I don't think you'll find any approaches that circumvent that basic problem.
    – Cody Gray Mod
    Commented Jun 20, 2014 at 8:14
  • 15
    @FrédéricHamidi: Did you read the last EULA you agreed to? Or the last interstitial ad you had to sit through? Did you read the manual for the last video game or electronic doohickey you bought? For me, the answers are all "no", so I can't really blame other people for not reading. Commented Jun 20, 2014 at 8:22
  • 4
    @user, honestly, in order: yes, no (I run a proxy that shields me from most ads / interstitials) and yes. (I have to admit I'm probably the last guy around that reads the manual before booting a game, but so there). Commented Jun 20, 2014 at 8:38
  • 10
    And what if the manual is incomprehensible ? I regularly try to find answers in the C++ Standard and believe me, not only is it difficult finding what you are looking for, but even when you found a related nugget there might be overarching rules (that you missed) or exceptions (elsewhere) that you need to take into account to obtain the final answer. Oh, and sometimes even with all the pieces the actual intent requires more divination than logic. How high do you place the bar ? Commented Jun 20, 2014 at 13:23
  • 9
    The stated purpose of SO is to create a library of Questions and Answers. It doesn't say anything about not creating redundancy with the documentation, but outlines specific opinions about "offline resources". I would say that teaching people to fish is generally a good thing, but outside the scope of this site. If you can answer the question, answer it. If the questions is a duplicate or inappropriate close it. End of story.
    – nsfyn55
    Commented Jun 20, 2014 at 13:34
  • 4
    You know, many folks do try to learn from Documentation (at least on game dev exchange), but sometimes, the documentation does not really help, or is in a language that a foreigner would not get it right. I would recommend asking in a comment if the person checked the docs, then proceed with the answer you receive. If they did not, well, I would give a -1 and tell the person to look into it before posting a question. We have to incentivate the person to research more, right?
    – Malavos
    Commented Jun 20, 2014 at 13:43
  • 5
    @nsfyn55 The post is adding zero value to the programming community. Every single person that was helped by that information would have found the exact same information with the exact same amount of effort had the question never existed in the first place, because they'd simply have found the documentation, seen the exact same content, and that would be that. Stealing content from an official source only to stuff it with your own ads while you work to get it better Google Juice isn't actually adding value to the world.
    – Servy
    Commented Jun 20, 2014 at 15:12
  • 5
    @Servy I think that is where we diverge. The stated goal of the site is as follows "With your help, we're working together to build a library of detailed answers to every question about programming.". You must note it does not say "every question that can't easily be searched somewhere else"
    – nsfyn55
    Commented Jun 20, 2014 at 15:32
  • 4
    @Servy I think paraphrasing documentation is more than appropriate. Part of what makes documentation suck is not just the content but the organization. I am checking out on this abuse of comments, but my final word SO is about building this library. It can/should have overlap with the documentation. I can/will/should answer questions that could be answered with copious offline research. I want to be able to find an answer to every one of my questions without leaving this site. If you think that is wrong then so be it.
    – nsfyn55
    Commented Jun 20, 2014 at 16:36

10 Answers 10

78

enter image description here

I dispute the premise of this question.

We can help askers read documentation, but in order to do so we will, by definition, write answers and comments — a kind of documentation. In fact this documentation persists on SO and has a name: "duplicates".

Will we then have to help people RTFA and RTFC? By writing more answers and comments? (Related: http://xkcd.com/1343/)

This leads to an intractable "turtles all the way down" meta-problem.

My answer is: Just point to the documentation*. Let the user have a shot at it. If the user tries to apply it and fails, then they can ask a question about that including what they tried, which is fine. If.

* In a comment, of course. Link-only answers suck. So do answers to non-RTFM questions more generally.

15
  • 18
    Your premise seems to be that the person read the documentation and was confused by it, not that they couldn't bother to read it so they wanted someone else to copy-paste it in an answer to them.
    – Servy
    Commented Jun 20, 2014 at 14:30
  • 1
    So instead, we should grab the entire documentation for that language, and put it in an incredibly large pastebin, and link to that pastebin in our answer, or just put the whole section of that documentation in the answer.
    – Justin E
    Commented Jun 20, 2014 at 15:34
  • 5
    The problem is that so much documentation is complete garbage. "Self-documenting code", for example is great for people who are experienced in both the programming language and the concepts being documented but not so great for people who are trying to learn either. I have seen so many libraries have great use of the language documented but have completely unhelpful documentation of exactly what it's supposed to do.
    – inetknght
    Commented Jun 20, 2014 at 15:59
  • @inetknght I guess people who want to read the manual but do not understand it may need a general programming course or a tutorial. Obviously there is bad documentation out there but also a lot of good one and most simple questions on SO could really be solved by reading more before. Commented Jun 20, 2014 at 16:10
  • 1
    @Trilarion: excepting the fact that a lot of boost libraries' documentation interfaces are complete crap, a lot of their actual documentation content is quite unhelpful too. There's libraries whose sole documentation is a doxygen pass on the headers.
    – inetknght
    Commented Jun 20, 2014 at 16:13
  • 1
    As someone that tries to write documentation for my own stuff, I find that I tend to have to spend at least twice or thrice as much time explaining how to use it or how it works compared to the amount of time required to understand the problem and provide a solution. It is reasonable that there's a lot of terrible documentation, if it even exists...
    – MxLDevs
    Commented Jun 20, 2014 at 16:18
  • 7
    @inetknght If, for a particular topic, the documentation doesn't cover it, or doesn't cover it effectively, and there are no other readily available solutions to the problem, then sure, SO is a great place to ask about it and get a good answer. But to assume that all documentation is universally bad and never worth using is just wrong. When the documentation covers a particular topic adequately, there is no need for that question to be asked on SO.
    – Servy
    Commented Jun 20, 2014 at 16:20
  • 1
    @inetknght Just went to the boost page and found more than just headers Example. But I don't want to fight over the quality of any documentation. Of course you can always make it better. And maybe this is the reason why SO exists. Commented Jun 20, 2014 at 19:35
  • I'm not going to argue semantics. Boost has gotten better in recent releases about having more than just headers as documentation. However, there's also the question about actually getting answers from people. Thankfully, you're right, SO is usually fairly good about that. :)
    – inetknght
    Commented Jun 20, 2014 at 19:56
  • Loads of Swing documentation is of the form "Frobs the foo according to bar", with no link to foo or indication of what it's for, no link to bar or indication of how to make one, and no indication of what frobbing might involve.
    – dfeuer
    Commented Jun 22, 2014 at 18:02
  • @Servy: How is that my premise? Or did you mean the OP's premise? Commented Jun 23, 2014 at 7:08
  • Admitting I upvoted this for humor... Commented Jun 23, 2014 at 7:58
  • Just point the user at the documentation = link only answer.
    – podiluska
    Commented Jun 23, 2014 at 8:08
  • @podiluska: ... link-only comment? Commented Jun 23, 2014 at 8:11
  • iOS documentation is abysmal.. this issue is platform-specific. Commented May 19, 2021 at 16:06
29

One of the best features of S/O, in my opinion, is the fact that so often it succeeds where documentation fails. This is for one of two reasons: the documentation is insufficient, or does not contain a good searching mechanism. Stack overflow (often via Google) is superbly searchable, and so it is often much faster to find the answer to a question here than it is to RTFM.

If someone asks a good quality (short, sweet, useful, non-duplicate) question, I think that's great even if the answer is in the manual. If nobody feels like bothering to answer it, that's fine too.

On a related note, my favorite answers often have a bonus link to the relevant documentation.

12
  • 14
    If the documentation fails to effectively answer the question then yes, SO is absolutely a great resource, but when users go and ask and SO question without even bothering to read the documentation, as you are advocating, it is highly wasteful of everyone's time and effort. Merely reading the documentation, when it contains a quality answer to your question, is far faster and easier than posting an SO question and waiting for an answer, it doesn't waste the community's time, it doesn't clog search results, etc. The flood of low quality questions like these also drives away experts.
    – Servy
    Commented Jun 20, 2014 at 18:44
  • 1
    I agree with some of your points, but not that it is wasteful. I've profited from it greatly just using Google day-to-day to look up trivial things (commands, etc.) that I've forgotten. Is S/O really only for experts to ask other experts questions?
    – AlexMA
    Commented Jun 20, 2014 at 19:26
  • And if the SO question wasn't there you'd just have found the documentation it was quoting, got your same answer, and been equally well off. SO added zero value to you in those instances. It adds value when SO is the only resource that has an answer to your question, or when it's answers are of far greater quality. When the answer of equal quality is already available, zero value was added.
    – Servy
    Commented Jun 20, 2014 at 19:32
  • 3
    "It adds value when SO is the only resource that has an answer to your question" SO is never the only resource that has an answer. If you are wondering why the questions that have hundreds of upvotes are often the most simple, RTFM type questions, it's because they have saved thousands of people meaningful chunks of time. Upvotes may not imply quality, but they do imply value. Thus, not a waste of time for the community. Just don't click on the question if it's too trivial for your taste.
    – AlexMA
    Commented Jun 20, 2014 at 20:03
  • But every single one of those people would have found the exact same information, in the exact same amount of effort, if that question never existed in the first place. No value was created from those users, value was simply taken away from the documentation (or whatever else is now in second place in the Google search for that post) in equal measure to whatever SO created. It saved thousands of people exactly zero chucks of time, contrary to your claim.
    – Servy
    Commented Jun 20, 2014 at 20:07
  • 3
    I disagree with you, and the bit about "value being taken away from the documentation" doesn't make any sense.
    – AlexMA
    Commented Jun 20, 2014 at 20:11
  • 2
    Imagine a site that just goes around re-posting every single SO question/answer on its own site, but also sticking in a bunch of their own ads into the content so that they make money. There's a ton of these sites. Do you think they're adding value? are the many thousands of people that get helpful answers there benefiting from the existence of that site? No, if those sites didn't exist, those users would just find SO instead, and get their same quality answer with the same amount of effort.
    – Servy
    Commented Jun 20, 2014 at 20:19
  • It's not the same thing, although I see where you're going with it. The difference, though, is SO creates new content, curates it beautifully, and puts it somewhere where it can be easily found and voted upon so the cream rises to the top.
    – AlexMA
    Commented Jun 20, 2014 at 20:22
  • It's exactly the same thing, at least in the cases under discussion, namely cases where high quality solutions to the problem at hand are already readily available. When the content placed on SO is not already readily available in other very high quality sources, sure, it does those things. When the official documentation already has all of that information in a quality canonical source then no, it's not adding value.
    – Servy
    Commented Jun 20, 2014 at 20:35
  • @AlexMA: I'm with you 100%. In fact, part of the original vision for Stack Overflow (and people can of course disagree with whether that vision still applies, or still should apply) is that it becomes the ultimate repository of programming knowledge. Implicit in that is that it will contain information that is already in other sources. But SO isn't meant to be (merely) links to those sources, it is meant to have the actual knowledge as content, in the form of questions and answers.
    – John Y
    Commented Jun 21, 2014 at 15:19
  • @Servy What's the alternative, that wastes less time? Commented Jun 22, 2014 at 23:58
  • 1
    @BenAaronson Don't waste your time answering questions that already have high quality readily accessible answers. Spend your time answering questions to which quality answers are not readily available instead.
    – Servy
    Commented Jun 23, 2014 at 13:54
8

I think learning by doing will work. The trick is how to get people to start reading in the documentation at all.

Suggestion:

Mention in your answer the existence of some interesting additional information about the topic. Do not explain that information, but include a hyperlink to it.

I think this can work well in short answers as well as longer ones.

7

Personally I like this approach:

From the man page: "Return Value -- On success, zero is returned. On error, -1 is returned, and errno is set appropriately."

This is followed by a list of errno codes and their causes. Which one of these is causing your failure will be apparent when you check the value of errno. The perror and strerror functions can automatically map the numeric value of errno to a short description.

It provides the next step in debugging (check errno), proves that what they need is in the documentation (the man page, specifically), and doesn't save them from actually having to read the documentation themselves.

The link too is helpful, but there are other ways to get a copy of the man page, so even if the link breaks the answer is still useful.

3

Answer the question and point them at the documentation.
My currently highest voted answer does this, and it seemed well-received.

This way, the first time a question about something comes up, we can respond, and every other time just point the asker the way of the answer, just like we always do on SO. It's not rude, doesn't push anyone away from the community, and still points out that you should RTFM. Typically questions like this can be answered in just a line or two, and if it can't then it's probably a question worth asking anyway.

1

Sometimes, the search in the documentation is not obvious. Python has great docs, that are divided amongst the library reference, the tutorial and some technical essays (not counting unofficial documentation). In this case, teach the asker how you know how to get to the documentation, and how to find it.

In other occasions, there is some jargon involved. It is easy to search the documentation, if you know the name (for example, views in Numpy arrays). Here, teach the jargon.

Other cases, the answer can be found by simply typing the post in your favourite search engine in the first three results. In that case, vote to close due to insufficient research.

-1

@user2357112 First, you're right that going for the manual is against the instinct and intuition of people, which is totally natural. There are no manuals in nature.

Having documentation that explains how to operate something, is a sign of imperfection, it means that the product is not self-explanatory, it has usability issues, it's arbitrary and unintuitive, it's interface is a puzzle that people can't solve and therefore it requires from the manufacturer or programmer to reveal the missing information -the information that the product fails to communicate to the user.

We all should aim to make products that don't need explanations. That goal alone will lead to human-compatible products, products with perfect usability.

Second, the point of your question is oxymoron. You post a question on a website about answering questions how to convince people who ask questions to leave the site and go find the answer in the manual instead!

1
  • Unsurprisingly, not that many agree with what I wrote. Obviously half of them consider that our current primitive era will be eternal, and the other half are those who make those arbitrary puzzling interfaces or write those lousy manuals and don't have a clue about how to make them better.
    – BEIC
    Commented Jun 23, 2014 at 22:30
-2

Should Stack Overflow really become the type of community where we redirect people away with a fierce and sarcastic mention to "Go read the manual!"? The only approach I see that doesn't deplete the usefulness of this wonderful community is to suggest ways the user could've answered their own question AFTER answering their question.

13
  • 4
    Yes. Absolutely it should
    – podiluska
    Commented Jun 23, 2014 at 8:09
  • @podiluska Elaborate on how that is a good way to go about a community. I find it narrow-minded to think this would - in any way - be beneficial.
    – CmdrSharp
    Commented Jun 23, 2014 at 10:33
  • @podiluska That is not elaborating on how it's a good way to go about a community. That's linking to discussion about the very issue I'm trying to bring forward. There is no reason to push people away because they don't follow the meta on S/O when they registered yesterday. We should welcome every new member, and make efforts to help them adapt to the community. Snide remarks won't do this. Read the accepted answer on this one. It kind of describes what I'm out for.
    – CmdrSharp
    Commented Jun 23, 2014 at 10:49
  • Except other answers to that have higher votes. Users that can't be bothered to RTFM should be treated with disdain. meta.stackoverflow.com/questions/257868/…
    – podiluska
    Commented Jun 23, 2014 at 11:08
  • @podiluska The votecount doesn't change what I used as an example to describe my thoughts. You're making wild and broad statement where you generalize people saying they can't be bothered to read the manual. This doesn't describe even nearly all cases being discussed, where the author is often new to the language and/or can't find the proper documentation - or even knows what to look for. Sit on a throne and look down upon these people genuinly seeking advice all you want, but in my book, that makes you a horrible member of this community, and I look on you with disdain.
    – CmdrSharp
    Commented Jun 23, 2014 at 13:50
  • 1
    Yes, when users are asking questions that consume the community's resources, add zero value to the site, but have a high cost, we should absolutely be encouraging them to read the manual first. SO was built with the premise that not all content is good content. It was designed to be a repository of quality questions with quality answers that will attract experts. Flooding the site with questions that just involve googling the question and posting the answer back to the user drives away experts.
    – Servy
    Commented Jun 23, 2014 at 14:01
  • Oh, and to whoever downvoted this when all I'm doing is trying to make a point very valid to the discussion - merry christmas.
    – CmdrSharp
    Commented Jun 23, 2014 at 14:11
  • @MarcusFrölander Voting on meta indicates disagreement - RTFM : stackoverflow.com/help/whats-meta (QED :) )
    – podiluska
    Commented Jun 23, 2014 at 14:15
  • 2
    @podiluska "On posts tagged feature-request, voting indicates agreement or disagreement". Read it yourself.
    – CmdrSharp
    Commented Jun 23, 2014 at 14:17
  • 1
    @MarcusFrölander When that traffic is encouraging more people to waste more of the community's time then that traffic that they are adding is harming the site, not helping it. Yes, flooding the site does drive away experts. When SO was first created it was designed with the premise of discouraging low quality questions which is why so many experts came to SO in the first place.
    – Servy
    Commented Jun 23, 2014 at 14:18
  • @MarcusFrölander Sure, I've never supported being rude, but not answering low quality questions, and instead expecting the user to do some basic research first, is not inherently rude.
    – Servy
    Commented Jun 23, 2014 at 14:31
  • @Servy I completely agree! :)
    – CmdrSharp
    Commented Jun 23, 2014 at 14:32
-4

I see this as two questions: What is 'good' documentation?

...And: 'Why do users come to Stack Overflow, even when I can show them good documentation that answers their question'?

There's no short answer to either question, so please take a moment to read a long one. If you don't have the time, here's the very, very short answer to the first one:

Manuals and documentation in general are written for more than one audience, and often they must be 'split out' into separate documents.

The common failure modes are:

  • Sometimes, users are reading the wrong one;
  • Sometimes, users have been *given* the wrong one and have no way of knowing that the other ones exist;
  • But, all too often, you have only provided one of them.

So what are 'The Documents' that constitute a good Manual?

I'm going to explain this using the example of a typical piece of commercial software, rather than for programming in general and the particular questions asked by developers on Stack Overflow because it allows me to lay out the principles and the categories of a good manual in a structured way.

Nevertheless, the principles of good documentation hold true for notepad.exe, or for the vast and complex world of Visual Studio for Enterprise; the differences lie in choosing which category of documentation needs to be prioritised, and how it should be presented.

And, of course, on recognising which developers count as beginners, 'occasional users', experts, and 'Support Manual' users in terms of how they need to use the documentation. This is not as easy as you think, and it is often done badly: you should ask yourself "Who was the intended audience for this documentation" before concluding that the reason it is useless, to you, is that the authors are useless.

You will still be correct in drawing this conclusion, more often than not: good technical authors are rare, and the role is not valued in most software houses.

So here's the basic documentation set for a moderately complex piece of software:

Getting Started:

  1. Congratulations on purchasing ACME software's latest product!
  2. Here's how to get it up and running;
  3. These are the three most common task you will perform, with a brief explanation and short set of screenshots;
  4. Where to get more information (links to help, an example of context-sensitive help, and a link to the full manual);
  5. Three 'cheat sheets' of menu paths and keyboard shortcuts for the common tasks.
There is a skill to generating the 'Getting Started' document: it's got to be short, relevant, and memorable.

For simple software, it is sometimes the only documentation that needs to be provided to the user.

If it isn't that simple, there are always going to be things that you missed, and problems that new users and owners run into at the very start, which you hadn't anticipated: you have to keep on top of this, keep talking to new users, and keep updating the 'Getting Started' guide.

Many vendor's don't.

There's also the problem of shipping software into a vast universe of (say) mobile devices, all of which are slightly different, and many of them will be out-of-date: in this case, there will be a need for separate 'Getting Started' help documentation. This, too, needs to be short, relevant, and memorable: a searchable 'Q&A' or FAQ page is probably best.

For much of the world's software, Stack Overflow is all of the searchable 'Q&A' in existence for someone getting started. Now there's no disgrace in The Stack being the best source of answers for some products - we're pretty damn' good! - but I have a very low opinion of vendors who are so bad that the 'Stack is the only source.

Stack Overflow is the first place that users will go when your documentation lists a short set of twee little 'troubleshooting' problems and doesn't provide a link labeled 'What to do next, if none of it works for you'.

If that's what the 'help' section of your 'Getting Started' guide looks like, please consider a new career contributing methane to a landfill site.

Onward, then, to The Big Document in 'The Documentation'...

The User Manual:

A user manual has three audiences:

  • Beginners;
  • Occasional Users;
  • Experts or 'Power Users'.
There is a fourth item, for a 'non-audience' of very special users:

  • Idiots.
I say 'non-audience' because they probably won't read the manual at all, but they are still represented in the 'do not do this' information that protects you against legal liability.

In the first three cases, your User Manuals have to support two separate and distinct activities:

  1. Learning to use the application and exploring additional functions after mastering the basics (the 'Training Manual' function);
  2. Looking up answers to specific questions about the functions of the software (the 'Reference Manual' function).

These two functions aren't really compatible: if you can fit them into a single document at all, you're going to structure it in distinct sections.

Structuring your information is really the key to all of this: far fewer people would ever look for 'Read the manual!' information on Stack Overflow if the manual provided a structured way to both read and retrieve the things they need to know.

I can't offer any guidance on the overall structure of your document - that's got to reflect the way it's deployed and used - but I can give you a tactical hint:

If every point that the users need to know is structured into these three sections, you will succeed in writing Good Documentation for beginners and for expert users:

  1. A memorable, meaningful, discoverable heading;
  2. The easy explanation and easy instructions;
  3. The details and the difficult stuff, if anyone needs to know more than the easy stuff.

You'll notice that I've mentioned beginners and experienced or expert users there, but not the 'Occasionals'.

Note that occasional users aren't beginners: they are often experts at one particular thing! So how does documentation work for them?

They don't need to wade through the introductory material, over and over again; but they do need 'reminders' if tasks they are performing (say) four times a year for quarterly reporting have a lot of separate steps.

The point about reminders isn't just that they are brief and to the point: they have to be easy to find, or you're forcing the occasional users to plow through all the documentation anyway.

A hint: a user manual with 'cheat sheet' sections of bullet-point lists of actions are very, very good for this: someone will adopt one of these and print it out for their own team's 'occasional user' task if you've done this documentation well.

So we get back to the structure of your document: does it make sense to each type of user, and does it work as both a training and a reference manual?

That's The Big One: now for the complicated one...

The Support Manual:

I'm going to deal with this lightly because there are very few generalisations that can be applied to good support documentation.

But the basics are:

  1. An overview of how the software actually works;
  2. The location of the error-reporting and debugging tools;
  3. ...And a worked example of their use;
  4. An 'FAQ' of the most common user error reports with worked examples of their resolution;
  5. A suggested 'first line support' script...
  6. ...And a searchable wiki or Jira-like vendor page of support issues, with details that are good enough to constitute a 'worked example' of each reported issue was resolved or worked around.

Some vendors do this; and some don't.

Some vendors supply 'recipe' instructions on what to do, but are very reticent about explanations: they don't quite believe that user support is often provided by people with more technical knowledge than the users.

In fairness, some vendors provide user support from a low-cost helpdesk with significantly less technical knowledge than the users, or even the office furniture; and it is perfectly logical for them to provide support documentation in the form of animated GIFs with catchy music and a popup reminding their supervisor to administer a 'Good Boy!' doggy-chocolate reward at key points in the 'support' process.

But the better class of vendor does provide a detailed support manual aimed at a technical audience, and so should you: it's hard to do, because we're a demanding audience... But doing it well is a reflection of your courtesy to your fellow-professionals, and some of us are going to remember having to work with the support manual at your last employer, when you are being interviewed for your next job.

I am, of course, assuming that you did it superbly.

But, in all cases, Stack Overflow is still the 'go-to' destination for answers, even when better information is available from the 'RTFM' official source.

Here's why:

The essential concept of discoverability:

I don't need to point out that both the teaching and reference functions of a manual should be searchable - although the training will lean towards a 'start from the beginning' narrative for some products - but the reference section and the 'Support Issues' list should be discoverable.

This means that it's not just possible to 'look up' details of the things that you know by name or keyword: 'looking up the details' means you know what they are, you know exactly what they are called, and you have a pretty good idea as to where the information is already.

If you know all that already, great, but...

Discoverability is about finding out what it's called and where it is

...Yes, even if you're from a different technical background to the authors of the document.

Example: "Oh, I can see that I need the word 'dimension' to do this, not 'table'..."

Counter-example: "Stooopid newbies are expected to know that we call this 'a dimension' and they need to spend an afternoon reading the training manual if they don't"

So the short answer to your second question is:

Stack Overflow has discoverability.

You can discover answers here that you won't find on other sites, even in the 'official' documentation, because unlinked information left as 'look it up if you know exactly what it is and where' isn't 'documentation'; it's a digital sarcophagus.

And if you can't discover it by Googling into the vendor sites, the 'Stack provides the ultimate discovery tool: asking people who actually know.

-12

Stackoverflow:

HAS REPLACED DOCUMENTATION.

That's how the world works. The world gets better. Read some Toffler books.

You might as well say: "Oh, I'm sick of these hotel review sites: people should get back to buying proper Fodor's travel guidebooks."

Or you might as well say: "How do I get people to stop using amazon.com and go to normal brick and mortar shops?"

Or, "How do we stomp out this Ebay use and get people back to Christies?"

Or, "How can we eliminate OkCupid use and get people back to using Bars and Discos?"

Or, "However do we stop people using this git + open source business, we must get back to jobs in companies."

It just doesn't make any sense. FORGET documentation, it's just stupid.

It was never a good idea. Documentation had it's little chance for a couple years and it's over. It's just something young people in the future will make jokes about from the Big Government era.

{Consider, have you ever bought - say - any Apple product. Did you see a manual in the box? No. Consumer goods are leading the way - documentation is just stupid; it's gone; it's historic. Nobody liked it and now it's history.}

SO + internet text search is here.


As I explain it below:

....When I can't remember "what the hell is the syntax of addRange in List..." I never, ever, ever go to the msdn doco page. Instead, I just start typing in Google the characters "List T add Ra..." and by the time I've typed those characters, I have the total answer.

(AND INDEED, as a highly non-trivial additional matter - this is a world-changing concept - I also instantly have, a vast range of additional ephemera, critical information about the issue, including - just one example - any new topical changes, any gotchas, and (astoundingly) all thinking on the matter by the handful of engineers/etc very closest to any topical issues on the precise technological item in question. Et cetera.)

Why would you possibly go "RTFM"? Google search is built in to everything everywhere in both text and speech, including eg my refrigerator door. And indeed the SO info-sphere is a critical part of the "google-info-everywhere" nexus.

19
  • 2
    People aren't searching. The same search that would turn up an SO answer would turn up the documentation. Also, without documentation, where is the information from SO answers supposed to come from? Trial and error? Reading the source? (Reading the binary, for closed-source systems?) The people I'm worried about here have an instinct to ask for help before looking for the information themselves, whether that information comes from documentation, duplicates, or other sources. Commented Jun 22, 2014 at 22:37
  • 8
    Rubbish. When Microsoft creates a new API, do they just let people figure it out themselves and post on stackoverflow? No, that would be ridiculous. They publish documentation on MSDN. Programming is a little more complicated than using an ipod. Documentation is required.
    – Blorgbeard
    Commented Jun 22, 2014 at 22:41
  • user2 -- if that's true, there's just a bad technology problem on SO. As a user types a new question, the site should just find all the answers. the site should further understand the user "is a newbie" and more aggressively present the info. So, they need a few lines of PHP to fix the problem you identify. The problem you identify would be not unlike saying "people don't know how to search, using the google page" .. if you see what I mean.
    – Fattie
    Commented Jun 23, 2014 at 7:08
  • @Blorg - I appreciate your gutsy "rubbish", but you sound like someone in the Kindle era moaning about how paper books and bookshops are still culturally important, or something. Nobody has ever, does ever, or will ever read Microsoft's documentation. You just google (which largely means "SO") for the answer, to even the simplest question. Just as software has gone "open source", all information is now open source. Nobody wants to and nobody does read the stupid doco, because there's a zillion infosphere tuorials, articles, thoughts in half-english, and SO entries on the subject.
    – Fattie
    Commented Jun 23, 2014 at 7:11
  • 1
    So, as you ask rhetorically, "When Microsoft creates a new API, do they just let people figure it out themselves and post on stackoverflow?". That is precisely, literally, exactly, to the letter what is happening with, say Swift. Which is a whole new language, a whole new milieu, not merely a new API. Nobody ever has, does, or will look at the stupid Apple pages on Swift. Everyone just instantly .. googles on SO. Look at the staggering amount of info on Swift on SO/the infosphere (after a few days). Nobody gives a toss what "the Man" (Apple in this case) has to say on the matter.
    – Fattie
    Commented Jun 23, 2014 at 7:15
  • The infosphere, created by you, my other SO friends, and my "sisterhood generally" of iOS engineers planetwide, is wildly better than the crap, government-esque doco "by the Man" which Apple provides. They should just stop pretending to provide it. You can (today, now) become a top Swift engineer, i.e. you can write software that will hold up suspension bridges, by absolutely not looking at the silly Apple doco, but by reading the zillions of thoughts in the infosphere. Trust SO :)
    – Fattie
    Commented Jun 23, 2014 at 7:18
  • 5
    Where do you think the people who post answers on SO get their information? The aether?
    – Blorgbeard
    Commented Jun 23, 2014 at 7:53
  • You are talking about tutorial(s) not documentation. You are confusing those two terms.
    – Abhitalks
    Commented Jun 23, 2014 at 8:03
  • @Blorg - you're just making "rhetorically funny" comments. The "rhetorically funny" answer would be "they watch the apple videos where engineers talk about it." (Actually that's not just funny, it's true: people so hate "manuals" that all the really deep source stuff on iOS (ie, on SO, on the infosphere) comes from those talks.) The fact is "everyone" (say, 999 people out of 1000) will never, ever, ever touch "The Man's" documentation about Swift. They'll get every detail from SO searches.
    – Fattie
    Commented Jun 23, 2014 at 10:06
  • @abh - no, you're quite wrong. When i can't remember "what the hell is the syntax of addRange in List<T>..." I never, ever, ever go to the msdn doco page. I just start typing in Google "List T add Ra..." and by the time I've typed those characters, I have the total answer, AND, importantly, a vast range of critical information about the issue, including - just one example - any new topical changes, any gotchas, etc. Why would you possibly go to the manual? Google search is built in to everything everywhere.
    – Fattie
    Commented Jun 23, 2014 at 10:08
  • (Recall too that if you have any, say, android device, lying around on your desk: you need only open your mouth and start saying the words "List add range syntax..." and before you can finish talking you'll have a vast array of information .. and as I outline in the previous comment, spectacularly better info than the doco, which is all-but useless, it's "basic".)
    – Fattie
    Commented Jun 23, 2014 at 10:10
  • I'm proud that two free thinkers have voted-up this post, which is so obvious. It's not even the case that "in two years everyone will think like this", it's already happened.
    – Fattie
    Commented Jun 23, 2014 at 10:11
  • 1
    I write docs, and I can assure you that plenty of people read docs. Not only do I know that from analytics, but we get a steady cadence of feedback and bug reports that make it clear that people read the docs quite carefully. I think the premise of this thread ("People don't read the docs") is too simple. Different people read different docs at different times; some people prefer docs, others videos, others a Q&A approach to their questions. (People often prefer different types of information at different times in their learning curves.)
    – mike
    Commented Jun 23, 2014 at 18:11
  • 3
    Joe, are you serious that you think people who answer questions on SO got their information from watching videos? Also, I like how people who agree with you are free thinkers (I guess the downvoters are sheeple).
    – Blorgbeard
    Commented Jun 25, 2014 at 5:14
  • 1
    Alls I'm saying is that we have plenty of quantifiable evidence that people DO go to the docs.
    – mike
    Commented Jun 26, 2014 at 17:02

You must log in to answer this question.

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