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?"

Comments

Documentation Shitty so Developers Turn to Web

[TheSpoom]

News at eleven.

Re:Documentation Shitty so Developers Turn to Web

[SJHillman]

I wrote a number of small utilities for my last company. There were times when I would delay deploying non-critical programs so that I could finish the documentation and this was always met with a "if you insist..." reaction. It was fairly common for me to find issues with the UI being unintuitive while documenting it, after which I would go back in and simplify things (and re-document).

Re:Documentation Shitty so Developers Turn to Web

[icebike]

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.

Re:Documentation Shitty so Developers Turn to Web

[Joce640k]

Yep. Microsoft documentation is truly awful.

Typical Microsoft documentation page:

DWORD throbTheWangle(DWORD Wangle, FLOAT HowMuch)

Description:
This function throbs wangles.

Input parameters:
Wangle - the wangle to be throbbed.
HowMuch - how much to throb it

Return value:
The function returns a status code indicating success or failure.

If you want to know what wangles are, what throbbing is, the valid range of "HowMuch", what the returned status codes are... well, you're off to StackExchange to see if anybody's managed to figure it out.

Re:Documentation Shitty so Developers Turn to Web

[JDG1980]

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.

Re:Documentation Shitty so Developers Turn to Web

[Z00L00K]

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.

Blame Google

[Anonymous Coward]

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.

Re:Blame Google

[geminidomino]

Only if you come from Google (or spoof your referrer to come from Google). They did that to evade de-listing for "deceptive indexing" or whatever.

Go to Expert Sex Change from DuckDuckGo or Qrobe, e.g., and you'll still find the answers behind their crappy little paywall.

How the hell do they even still exist, in a world with StackOverflow, anyway?

These are two different use cases

[Hentes]

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.

It's not the the docs are bad or not used

[Megahard]

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.

Re:Astroturfing Detected

[binarylarry]

Don't worry, he's just making sure none of us get Scroogled.

Use of Stack Overflow != Bad Documentation

[HaeMaker]

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.

That's why I like(d) PHP docs

[kompiluj]

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).

Re:What would I do without the web?

[fritsd]

[This page intentionally left blank.]