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

Useful documentation is rare

[us7892]

Useless busy-work after-the-fact documentation is overrated and plentiful.

Useful documentation is rare.

Re:Microsoft docs

[dkf]

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.

I have always used Google (in site-search mode) to find things on MSDN; it usually gives me exactly the right hit as the top one (even when I use the "wrong" search terms) and I can't remember the last time when it wasn't on the first page of results. Bing search has never worked as well for me. I have no idea why; it's not like the information is impossible for MS to index or something.

However, Stack Overflow has some key advantages over a straight documentation search. You get worked examples, usually with community feedback as to which ones worked for them. You also get links to the right places to look in the docs. Finally, SO have a mechanism in place for handling dupes; Google like them a lot because they indicate clearly that a question asked one way is really the same question but asked in a different way. For a search engine that doesn't really understand very much at all, that's super-valuable info. (The downside of SO comes when there just isn't an expert around to answer questions on a particular topic; you can get a build up of unanswered questions that benefit nobody.)

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

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:Astroturfing Detected

[Kjuib]

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.

Re:What does StackOverflow run on?

[Anonymous Coward]

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.

Re:Blame Google

[MightyYar]

If MS's built-in search worked nearly as well as Google, we wouldn't have to Google it. The sad thing is that I even use the Google search engine to search on MS's site. Even sadder is that Bing results aren't half bad, so they already have the tech in-house.

Re:Documentation Shitty so Developers Turn to Web

[WuphonsReach]

Things also go missing. You will find something this week, only to find it missing with the next update to the website.

This is their biggest sin by far in terms of documentation.

Used to be that their URLs were nice, short and made sense. Then they rewrote everything and broke all the URLs just so they could do some weird frame in a frame nonsense that went against most web UI standards.

The suits in charge of the documentation web at MS are clueless, each one wants to put their own stamp on things by rewriting everything during their tenure.

I gave up trying to bookmark anything at Microsoft.com a decade ago (also about the point I started moving away from Microsoft for all software where possible). Instead, if it's absolutely vital reference documentation, it gets printed to a PDF file and stored locally.

They're not the only sinners in that regard, way too many other companies around the web constantly shuffle their documentation URLs around, breaking all the old links.