Slashdot Mirror
Developers May Be Getting 50% of Their Documentation From Stack Overflow
New submitter gameweld writes "Software companies, such as Microsoft, create documentation for millions of topics concerning its APIs, services, and software platforms. Creating this documentation comes at a considerable cost and effort. And after all this effort, much documentation is rarely consulted (citation) and lacking enough examples (citation). A new study suggests that developers are increasingly consulting Stack Overflow and crowd-sourced sites over official documentation, using it as much as 50% of time. How should official documentation be better redesigned? What are the implications of software created from unruly mashups?"
News at eleven.
It's better to vote for what you want and not get it than to vote for what you don't want and get it.
- E. Debs
Whenever I have a problem, I google it, and StackOverflow is always in the top of the results. If Microsoft want me to use their documentation they better make sure google indexes it in a way than matches my queries.
Documentation and asking others for help when you get stuck complement each other. You can't really learn to use something completely new on Stackoverflow, and you can't predict all the ways people will screw up or misunderstand you in a documentation.
I don't want to pay $36 to read the study, so I can't comment directly on it, but
| Microsoft's MSDN website changes frequently, and is confusing to use (on some iterations of their website, on others it works better). Currently to find anything, you have to use the Bing search on their web page, and it doesn't always work well. I find myself using Google search to search for functions in MSDN, because I get better results.
As a result, if something for Stackoverflow comes up in the search results ahead of the MSDN docs, I'll probably look at that one. From that, I hypothesize that if people are looking at Stackoverflow, it's because they've done their SEO better (and probably have more motivation to do SEO).
"First they came for the slanderers and i said nothing."
The problem is lack of usage examples and feedback. When you follow the API and your program doesn't work, the solution is to google your problem to find the solution from the 1000 others who have hit the same problem.
I eat only the real part of complex carbohydrates.
Useless busy-work after-the-fact documentation is overrated and plentiful.
Useful documentation is rare.
With documentation you usually just get an API reference, and maybe a simple example. With community sites like Stack Overflow you get vetted examples and best practices from real world users. It's almost always more helpful than just a static reference.
A good coder will write good code even in a bad language. A bad coder will write bad code even in a good language.
But let a good coder use a good language, and you'll get great code. Just don't let a bad coder use a bad language, else you get, well, 90% of the stuff in VB6.
I know most of the answers I give out on StackOverflow are really just paraphrased MSDN documentation. StackOverflow just acts like a new aggregator in that sense I guess. It's not the source of information, but a place where information from other places comes together.
For some development problems it is far quicker to search sites like Stackoverflow for a question / answer / example relevant to your specific case than it is to read the official (often poor) documentation and figure out exactly how it is "supposed" to work.
Basically, someone else did the work - possibly found some "gotchas" - and shared the fruits of their labour. Remind me how is that a bad thing? Isn't this exactly what the World Wide Web was designed for? :-/
Peace,
Andy.
All or nearly all of your comments are pro-Microsoft and anti-Microsoft competitors.
It's better to vote for what you want and not get it than to vote for what you don't want and get it.
- E. Debs
The nice thing about Stack Overflow (and such) is that someone, somewhere, has (usually) encountered the same problem I am currently working on. The official documentation I check when I want some basic examples on how to use something and what the different methods are supposed to do.
I may have created a few mashups from examples, but most of them weren't all that unruly. Perhaps the implication is that the wheel isn't invented all that often?
It is what it is.
The official documentation and message boards serve two different purposes, The official documentation should be a complete reference to the API and structure of a language. This is necessary for completeness. Stack Overflow should be used for quick real-world examples of simple tasks to be used as a starting point, or to get help with a particularly nasty bug.
We need both approaches, and the success of one, does not indicate the failure of the other.
This is not to say official documentation doesn't fail for other reasons, but killing it in favor of Stack Overflow alone is not the answer.
You can't really learn to use something completely new on Stackoverflow,
StackOverflow is probably not the best place to pick up programming in a new language or platform, but for understanding new (to you) parts in a system you already know a bit SO usually produces more practical examples, sometimes with example code doing exactly what you are trying to get done.
"There is more worth loving than we have strength to love." - Brian Jay Stanley
The major thing for me is that the official documentation is written based on how someone at the vendor thinks the software ought to be used, while StackOverflow shows how it's actually used in common cases.
Example: I needed a custom configuration section for app.config/web.config for a .Net application. I laid out my XML to be readable by the people who'd have to maintain the configuration. When I went to the official documentation, did I find any examples showing common XML layouts and how to translate them into the code to implement them? Nope, not a bit, just examples of "correct" code with snippets of the XML they'd produce. None of which matched common patterns, BTW. I was looking for a simple top-level BUREAUS element containing multiple BUREAU elements with the bureau name as an attribute, each in turn containing multiple KEY elements with name and value attributes to hold each bureau's configuration settings. StackOverflow and other sites were the only places that gave me actual useful examples of taking an XML layout and turning it into the .Net configuration section code matching the XML.
The best thing I can recommend for official documentation is to stop including just the official "this is the way we intend it to work" description. If you intend it to be used one way, explain why this is the best way to use it. And then go looking at sites like StackOverflow for how people actually want to use the APIs. If what people are asking to do doesn't match the intended usage, start asking yourselves "Why?". Think long and hard about it, because in the real world what my boss wants done always, always trumps what the vendor thinks (my boss signs my paycheck, the vendor doesn't). And then adjust your documentation to include examples that line up with what developers are actually asking to do.
Android document is pretty bad as well. Everything is explained assuming you read everything from cover to back and understood. Except it is not a book so there is no start and no end.
So it is good for looking something up, but for learning or understanding a problem the documentation is not sufficient.
StackOverflow on the other hand plays the role of a huge FAQ.
Minor rant, but look at the "InConnectionString Argument" section (which I can expand/collapse [useless] but can't link directly to, which is annoying) of this page. Try to read their grammar for a connection string. Confused yet? There are line breaks that have completely disappeared, causing words to merge together (e.g. "connection-stringattribute" should be "connection-string" with "attribute" being on a new line). I filled out the little "did you find this helpful" thing at the bottom of the page explaining the problem a year ago, and it hasn't been fixed. Dumping half-assed documentation on the web and not fixing (reported!) errors wastes the time of each individual developer that has to read/decipher it. The PHP online documentation is one of the most useful ones I've found, largely because it allows users to add comments/examples that make things clearer. Microsoft does the opposite -- not only can users not add to it, but the improvements that users suggest (through the "did you find this helpful" thing) are ignored. Perhaps all of the useful information is on StackOverflow because Microsoft doesn't allow it to be added to their own documentation.
More generally, it should be easy to bookmark pages (URLs should NOT break, even when new versions are released!) and sections within pages so it is easy to refer back to important things, as you could with paper documentation. Documentation for each function/object should link back to an overview that explains how it fits into things, and it should link to examples that show how all of the arguments (not just one special use case) works. Documentation should explain any differences between new/old behavior of any function/object because not everyone is developing for the latest version of the OS or development platform. And, just to beat a dead horse, users should be able to submit improvements/clarifications that actually get used.
A lot of Stack overflow questions I see are along the form of "I need to do X, how do i do it?".
Basically they want a HOWTO of which APIs to string together in order to accomplish their task, if not someone else to completely code it for them. This is often referred to as "task based" documentaiton - to do X, you do A, B, C, and D. This often fails if you need more details on individual API calls.
Official documentation like MSDN exist to document all the APIs, but often lack what's known as "task-based" documentation.
They're both required pieces - task based is often used to learn how to do things (e.g., how to create a window on Windows), while the API documentation serves to comprehensively adjust various settings (do you want a scroll bar? A resize box? etc). Unfortunately, putting in extensive examples inside such documentation often serves to confuse (you won't believe how many people assume you can copy and paste it into a program and have it run).
Unfortunately, Stack overflow also suffers from developers merely copying and pasting code and expecting others to do their work for them (see thedailywtf), as well as many "give me the codez" stuff posted by students wanting others to do their homework.
But when used properly, the two complement each other. Its like man pages versus HOWTOs on Linux - one documents the commands and APIs, while the other tells you how to properly string them together to accomplish things.
You're ignoring what stackoverflow is usually used for, which is to ask specific questions that aren't clear or aren't available in the documentation. For example, if you ask 'How do you use Bash?' or 'What does the -F option for ls do?' your question will most likely get deleted by a moderator or get downvoted out of existence, along with several angry comments that say 'read the f*&^ing documentation.'
When you write, do you form and choose your prose based on the dictionary on your desk (or online)? Of course not. A dictionary is the ultimate reference for words in your language, though. If you have a word, you can look up its part of speech, spelling, definition, pronunciation, even sample usage in some cases. But if you're writing an essay, or a book, or a brief, or a memo, a dictionary is very close to unusable. If you want to describe the action of a bipedal animal moving swiftly over land by means of propulsive contact with the ground, you're not going to find what word to use in a dictionary. If you don't know what the word run means, or how to use it, a dictionary is ideal.
Sometimes - no, often - the official documentation is exactly the *wrong* reference to use when creating from scratch. I'm not a programmer, but anyone who has ever even used software to do anything - from Autocad to Wordperfect - knows that the official documentation is almost never going to give you a useful answer to a problem you are having. You have to know the command to use before you can look it up. I still have programs whose documentation is a list of definitions, in order, of every menu and submenu command. And when I get stuck, I know that the answer I'm looking for is never going to be in that "help" file.
Is it just my observation, or are there way too many stupid people in the world?
In PHP docs with every item there comes the section for for "user contributed notes" which are sometimes pretty insightful (like there php strings intro or there implode string function ). Long time ago in a galaxy far away when I used to code in PHP those useful comments not only usually saved my day, but somehow compensated for the unorthogonality (well, an understatement) of the PHP standard library and the language itself. So - yes - I definitely prefer using worse language with better docs than the other way round (think Haskell vs PHP).
You can defy gravity... for a short time
It depends on what you are using it for. PHP is great for sites with a very small number of pages. There are no bad languages, just languages being misused.
Morse Code is a great language for certain purposes. But you don't use it when speaking to someone in person. Baby talk is a great language for certain purposes. But you don't use it in a meeting with your bosses.
How should official documentation be better redesigned?
It should exist.
There are even some very good games written on .NET, and, surprise surprise, and they are very decent. Of course, if you dont expect a first person shooter with UT3 engine behind the scene...
If your car analogy to my car analogy was a car, it would implode and form a car analogy black hole and radiate its analogy away as a hard car analogy emissions.
Why change it if it still does what the company needs it to.
This brainwashing we are experiencing that we need to update everything all the time...is hogwash!
A bike is still a bike...so if you can get from point a to point b, why trade in your old bike for a newer and 2000$ prettier bike???
A bike is still a bike...so if you can get from point a to point b, why trade in your old bike for a newer and 2000$ prettier bike???
You wouldn't. But when the frame finally goes, you might consider replacing all of the other components and not just the frame. And if technology has moved far enough, it can get harder and harder to find an affordable frame that fits and works with your ancient components.
I'm not being obtuse... this is a real problem. There are whole factories that run on commodity DOS hardware from the early 90s. It starts to get very hard to replace that old hardware... at the point where you find yourself hitting eBay, you should probably accept that you are on borrowed time and plan a transition to newer stuff.
W..w..W - Willy Waterloo washes Warren Wiggins who is washing Waldo Woo.
Mod up. That is how I end up on the code project and stack over flow. My most recent task is:
How do I send a client certificate with a POST request from c#? First time I've had to do any of that.
So I use some basic google-fu turn that into a sensible keyword search and you get a few examples from forums, including stackoverflow.com, support.microsoft.com, forums.asp.net, c-sharpcorner.com, etc.
Its not until about halfway down page 2 of googles search that I get ANYTHING from MSDN. And when I do its an article on
ClientCredentials.ClientCertificate Property of System.ServiceMode.Description, which is at least tangentially relevant but not at all directly useful.
But after reading a few forum articles on it, I know that I'm going to be using HttpWebRequest, and I'm going to use its ClientCertificates collection, and I'm going to need an instance of an X509Certificate object. (Or X509Certificate2)
If I need more information on those classes then I'll head over to the official documentation. Or not. If the article example and discussion was sufficient for my needs then I might not need to go further.
API documentation can't be improved, I don't think, becuase it documents the API. I often don't really need much API documentation, I need the "tasks to relevant classes" mapping.
I have the same problem with linux to be honest. Man pages are great but I'm usually stuck where I don't even know what command I need to use for the task I want to accomplish.
For a trivial example: How do I rename a folder in linux?
Lets look at the resuts:
top results, various forums and FAQs and basic information that amounts to:
hey its really easy:
mv old-folder-name new-folder-name
I don't see a man page until page 2 of the results. And ugh, its a man page for rename(3), the C function, which is not what im looking for.
I don't actually seen the man page for mv in the top 5 pages (I didn't check further). I'm not surprised. Sure the Description in the man page for mv is:
Rename SOURCE to DEST, or move SOURCE(s) to DIRECTORY.
And the rest of the page is documentation of syntax and switches, like -S to override the usual backup suffix, or -u to move only when the SOURCE is newer then then destination or the destination file is missing... etc etc etc.
There is nothing wrong with the man page but its no wonder we don't see it ranked higher than countless forum and FAQ articles on basic linux file operations.
There are no bad languages, just languages being misused.
Oh so very wrong.
There are even some accidentally bad languages, but of the commonly known languages, yes, they tend to be good for some purposes.
I'll agree if you specify PHP4. PHP5 can be used responsibly.
W..w..W - Willy Waterloo washes Warren Wiggins who is washing Waldo Woo.
Documentation should be the absolute authority on every detail of a system's operation.
The Documentation has a huge problem. It lays out how the thing in question was MEANT to work.
What StackOverflow offers is understanding of how it ACTUALLY works (or doesn't).
Furthermore Documentation is written almost always with either very generic examples or examples imagined by the documentors or framework builders. StackOverflow offers examples from people who are trying to build something real that works.
"There is more worth loving than we have strength to love." - Brian Jay Stanley
Google the name, with MSDN as one of the search terms, land exactly on the appropriate MSDN page, read the format, check that I have the required headers, code the call and... ...then you look on StackOverflow to figure out why the call didn't work like you thought it would.
"There is more worth loving than we have strength to love." - Brian Jay Stanley
[This page intentionally left blank.]
To be, or not to be: isn't that quite logical, Slashdot Beta?
Baby talk is a great language for certain purposes. But you don't use it in a meeting with your bosses.
You haven't met my boss. Baby talk is by far the most efficient means of communication. I've been known to reward him with lollipops occasionally if and when he behaves himself.
Microsoft (et al) are good for answers to questions like:
how does (x) work (what are the details of (x) )
Stack Overflow is good for answers to questions like:
how do I do (x).
Really, really, really different types of questions.