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.
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.
Don't worry, he's just making sure none of us get Scroogled.
Mod me down, my New Earth Global Warmingist friends!
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.
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.
When all else fails, read the directions.
Documentation should be the absolute authority on every detail of a system's operation. It should be the reference material for experts. On the other hand, people who aren't experts don't know the available options, and often don't really know the terms to look for in the detailed documentation, and can't spare the time or effort to read (and grok) the whole documentation end-to-end. StackOverflow is a great place to describe the problem you have, and experts (who know the system more fully) can point you in the right direction or even provide a solution. Then you can read the relevant documentation to understand better what's going on, and hopefully provide similar help to others.
You do not have a moral or legal right to do absolutely anything you want.
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.
It is one our test for hiring a new developer. "If you google for help and there are 2 links, stackoverflow and somethingexchange which one do you click on?" If they don't say stack overflow, then they haven't done enough real world work for us.
- Your stupidity got you into this mess, why can't it get you out? -Will Rogers
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.
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
[This page intentionally left blank.]
To be, or not to be: isn't that quite logical, Slashdot Beta?