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?"
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.
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.
Lots of truth to this.
What you get from MSDN must be read like a lawyer parsing the law books.
Miss some casual reference and the whole API call fails. Or worse, it almost always works, but
fails inexplicably on odd numbered Tuesdays.
Things also go missing. You will find something this week, only to find it missing with the next update to the website.
That said Microsoft documentation is still more extensive than most. I often start there then end up on Stackoverflow
of one of the other sites for more lucid examples, and often find that problems with a particular feature not working
as documented are common knowledge, except, apparently, to Microsoft.
Sig Battery depleted. Reverting to safe mode.
One of the most annoying things about the MS API documentation is all the unexplained dependencies. You see a function call that takes 2 structure pointers as parameters and returns another structure... now you've got to open 3 additional documentation pages to read what those structs mean. And they might contain other structures of their own, so soon you can be up to half a dozen or more tabs, all for one API call you want to perform.
Microsoft and others writes a kiloton specific for the function it concerns, but nothing about the context in which it shall be used. Here's what StackOverflow is a lot better at - a lot of examples, some good, some not so good and some esoteric.
If builders built buildings the way programmers wrote programs, then the first woodpecker would destroy civilization.