×

Welcome to the Slashdot Beta site -- learn more here. Use the link in the footer or click here to return to the Classic version of Slashdot.

Thank you!

Before you choose to head back to the Classic look of the site, we'd appreciate it if you share your thoughts on the Beta; your feedback is what drives our ongoing development.

Beta is different and we value you taking the time to try it out. Please take a look at the changes we've made in Beta and  learn more about it. Thanks for reading, and for making the site better!

Developers May Be Getting 50% of Their Documentation From Stack Overflow

Soulskill posted about a year ago | from the not-half-bad dept.

Programming 418

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

cancel ×
This is a preview of your comment

No Comment Title Entered

Anonymous Coward 1 minute ago

No Comment Entered

418 comments

What does StackOverflow run on? (-1, Troll)

mystikkman (1487801) | about a year ago | (#43081943)

Interesting Stackoverflow runs on the .NET platform and is very fast despite the extreme load.

So much for Slashdot's wisdom that .NET sucks. Meanwhile Reddit on PHP or Python is superslow and is overloaded.

Re:What does StackOverflow run on? (4, Insightful)

gman003 (1693318) | about a year ago | (#43082023)

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.

Re:What does StackOverflow run on? (-1)

Anonymous Coward | about a year ago | (#43082391)

90% of the stuff in VB6

As reddit would say... So brave... G_G

Re:What does StackOverflow run on? (1)

Anonymous Coward | about a year ago | (#43082435)

VB6?! You had to reach pretty far back for that reference. You might as well throw in RPG while you're at it.

Re:What does StackOverflow run on? (1)

ByOhTek (1181381) | about a year ago | (#43082463)

To an extent... but there's only so much you can do if the tool is pretty screwed up.
Fortunately, I don't think there's any major tool out now that is that bad. Though the headaches to get past a bad language/framework are *not fun*

Re:What does StackOverflow run on? (0)

The Raven (30575) | about a year ago | (#43082493)

Sorry, but PHP is a better example of a bad language than VB6. Not that VB6 was good... but PHP is far worse.

Re:What does StackOverflow run on? (4, Insightful)

Bigby (659157) | about a year ago | (#43082617)

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.

Re:What does StackOverflow run on? (2)

stanlyb (1839382) | about a year ago | (#43082697)

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

Astroturfing Detected (2, Insightful)

TheSpoom (715771) | about a year ago | (#43082059)

All or nearly all of your comments are pro-Microsoft and anti-Microsoft competitors.

Re:Astroturfing Detected (1)

DutchUncle (826473) | about a year ago | (#43082269)

A lot of IT people feel that way too. It works, sort of, they know how to keep most users happy most of the time, and it's reliable at what it does. It's like fast food, or maybe a fast-casual chain restaurant. Children might even prefer its predictability. It has its place in the world.

Re:Astroturfing Detected (1)

Richard_at_work (517087) | about a year ago | (#43082551)

I could mod you down, but I won't - I shall reply to you instead.

If you look at my comment history, you will see a lot of pro Microsoft stuff there, but that doesn't mean I'm astroturfing or even linked to MS in any way other than being a .Net developer and satisfied Windows user.

Having pro-something and anti-something else in your history doesn't mean anything more than you have a strong opinion on that something.

Re:Astroturfing Detected (2)

pixelpusher220 (529617) | about a year ago | (#43082679)

Well to be fair, if you're Pro 'X' and anti-'people against X', you're still pretty much fully pro 'X'. And around here, that's more than beyond a reasonable doubt to convict and string you up on your .NET horse your rode in on! ;-)

Re:What does StackOverflow run on? (0)

Anonymous Coward | about a year ago | (#43082065)

When using StackOverflow, I search using Google, then fall directly on my web page, then I - Back then search for something else.
When on Reddit, I click everywhere and read everything...
you can't compare both load.

Re:What does StackOverflow run on? (-1)

Anonymous Coward | about a year ago | (#43082153)

Downmod parent, please. Check post history - he's a microsoft shill.

Re:What does StackOverflow run on? (0)

Anonymous Coward | about a year ago | (#43082501)

Someone downmod this $hill linfaggot

Re:What does StackOverflow run on? (1)

Anonymous Coward | about a year ago | (#43082191)

The entire stack isn't microsoft. In fact only the site and database are microsoft. They also use redis. Have several Linux servers. (Ubuntu and CentOS) HAProxy, Bacula, Nagios...

Re:What does StackOverflow run on? (0)

Anonymous Coward | about a year ago | (#43082195)

Reddit on PHP?

Have you been living under a rock or something?

The source is on Github, dude.

Documentation Shitty so Developers Turn to Web (5, Funny)

TheSpoom (715771) | about a year ago | (#43081945)

News at eleven.

Re:Documentation Shitty so Developers Turn to Web (4, Insightful)

Looker_Device (2857489) | about a year ago | (#43082243)

It would probably help if more companies paid for the technical writers to do it themselves. Unfortunately, if they're anything like the last shop I worked at, the documentation was one of the first things that got shortchanged when times were tight.

Re:Documentation Shitty so Developers Turn to Web (5, Interesting)

SJHillman (1966756) | about a year ago | (#43082311)

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 (5, Insightful)

icebike (68054) | about a year ago | (#43082335)

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 (2)

blackraven14250 (902843) | about a year ago | (#43082643)

I've had pretty much the same experience, where anything that isn't Java or MySQL has landed me on SO or another site instead of the official documentation.

Re:Documentation Shitty so Developers Turn to Web (5, Funny)

Joce640k (829181) | about a year ago | (#43082581)

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 (3, Insightful)

Anonymous Coward | about a year ago | (#43082661)

This isn't just Microsoft documentation either. I wish you were exaggerating, as it always amazes me how little people must give a crap if they write this and think it's acceptable documentation.

Re:Documentation Shitty so Developers Turn to Web (5, Insightful)

JDG1980 (2438906) | about a year ago | (#43082663)

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.

Blame Google (5, Insightful)

Anonymous Coward | about a year ago | (#43081959)

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 (3, Insightful)

gl4ss (559668) | about a year ago | (#43082145)

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.

..and when they do that, better make fucking sure they're not doing an annual switching around of documentation site urls during that time, landing you on a wild goose chase - only to find documentation that is vague about the answer for political reason or documentation that is just a brochure of the sdk with promises about what the sdk does but not actually telling how, why and what actually works.

AND I DON'T FUCKING WANT TO ANSWER A QUESTIONNAIRE ON MY FIRST FUCKING VISIT ON YOUR FUCKING DEVELOPER SITE. how the fuck am I supposed to know if I found what I came looking for?? (Nokia used to run these quizzes every 6 months. fucking annoying - especially when it was an indication of that they were putting a lot of money into their dev stuff but not getting much out of it). and I most definitely don't want a fucking pdf essay 10 pages in length that _might_ have the answer(but more probably has just lies about what they thought the api would behave like).

but yeah, stack overflow comes up so often on "how to do blabla on blebleble" things that it's where devs quite often end up. and why shouldn't they, if the answer is right there or a link to an answer. oftentimes it's more current than actual docs anyways.

a rather important aspect of this whole "getting information from" is that most devs are not asking questions and receiving answers - they're reading other peoples questions and answers to them because it's quite rare to have a really unique installation problem, a rare api bug that nobody else hit or a rare question about how to get some layout engine xyz to behave in ysz way. so it's not about being lazy, it's about finding information and saving time, not getting other people to do the work for them.

Re:Blame Google (2)

ByOhTek (1181381) | about a year ago | (#43082393)

At least it's not full of Expert's Exchange any more. Though the trick with that one, rather than pay, is just keep scrolling down, after a bunch of idiotic links, you'll see the answers they tried to hide below what looked like a footer.

Re:Blame Google (5, Insightful)

geminidomino (614729) | about a year ago | (#43082507)

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?

Re:Blame Google (1)

Joce640k (829181) | about a year ago | (#43082675)

..and when they do that, better make fucking sure they're not doing an annual switching around of documentation site urls during that time, landing you on a wild goose chase

Also don't send me to an intermediate page that pops up a window: "Warning: The contents of this page are unencrypted, are you really 100% sure you want to read the Microsoft documentation? (Y/N)"

(or whatever that damned message is that appears every single time I go from Google to MSDN...)

Re:Blame Google (1)

DutchUncle (826473) | about a year ago | (#43082291)

And that their page actually has some content on it instead of cross-referencing some other MSDN document that I can't get to.

Re:Blame Google (1)

ByOhTek (1181381) | about a year ago | (#43082345)

I'd say that's about right.

People Google, SO usually comes up first. If I'm fairly API specific, I can generally get something from the manufacturer page. For example, if I have the full path to a calls (or simply a namespace) - I usually get the Microsoft (C#) or Oracle (Java) documentation initially.

About the only time I go and look at the documentation directly is/was in Python, PHP, and LibSDL, who managed to have good organization to their stuff, compared to a lot of other groups. Though for examples in the document, I'd only complain about Java and LibSDL, and in both cases, the descriptions are usually sufficiently clear, except when the quirks aren't mentioned in Java.

Re:Blame Google (0)

Anonymous Coward | about a year ago | (#43082413)

I guess it depends on how you construct your query and whether it is specific to the API you are looking for or is a general "how to". For example most of my API documentation queries are very specific - such as this:
site:msdn.microsoft.com DhcpRequestParams
This will give me the exact documentation I want from the official source. But if you wanted to be able to query like this:
"How do I get DHCP parameters in code from Windows 7"
then, yes, you are going to get a lot of unofficial sources and most of the results will have nothing to do with what you wanted.

Re:Blame Google (1)

cruff (171569) | about a year ago | (#43082545)

If Microsoft want me to use their documentation they better make sure google indexes it in a way than matches my queries.

Perhaps you should switch to using Bing, then your query responses might match up with what Microsoft wants? :-)

These are two different use cases (5, Insightful)

Hentes (2461350) | about a year ago | (#43081963)

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.

You can learn something new from SO (2)

SuperKendall (25149) | about a year ago | (#43082115)

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.

Re:You can learn something new from SO (4, Insightful)

Sarten-X (1102295) | about a year ago | (#43082559)

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.

Re:You can learn something new from SO (1)

fuzzyfuzzyfungus (1223518) | about a year ago | (#43082699)

Aside from the trivial case(systems so undocumented that they are, themselves, all the documentation that exists), has anything ever reached the state of perfection where The Manual is actually authoritative?

Microsoft docs (4, Insightful)

phantomfive (622387) | about a year ago | (#43081985)

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

Re:Microsoft docs (3, Interesting)

dkf (304284) | about a year ago | (#43082293)

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:Microsoft docs (1)

i kan reed (749298) | about a year ago | (#43082343)

Actually, it doesn't change frequently. What I've discovered is that it skins itself depending on where it got linked from, making web search results a crapshoot.

Re:Microsoft docs (1)

earlzdotnet (2788729) | about a year ago | (#43082531)

Very **VERY** frequently the biggest problems I see on MSDN isn't finding the documentation. It's finding completely inadequate or incorrect documentation

Example: DefaultOverLoadAttribute [microsoft.com] -- "Indicates that a method is the default overload method" Wow, that's informative! And of course they don't give ANY links as to what the purpose of including this was, or saying when to use it

I commonly will have questions on Stackoverflow asking for help understanding what the hell MSDN is trying to say. For instance this question [stackoverflow.com] It's a question asking "MSDN says this, but I see this. Why?" with the answer boiling down to "MSDN is very misleading"

Or there is crap like DependencyProperty.RegisterAttached [microsoft.com] "here's a hint at what this does..." oh, btw, there's a magic naming convention we're not going to explain at all HAR HAR HAR

slashvertisement (0)

Anonymous Coward | about a year ago | (#43081987)

How is this anything other than an ad for StackOverflow?

Re:slashvertisement (0)

Anonymous Coward | about a year ago | (#43082459)

It's not. It's just questioning whether traditional documentation sucks and inviting our discussion on the matter. Is there another Q&A site that should have been mentioned as well?

Re:slashvertisement (1)

mark-t (151149) | about a year ago | (#43082521)

While I can see how it might be perceived as such, I might suggest that it may only be seen that way by people who haven't found the Q&A style of stackoverflow helpful at some point.

Re:slashvertisement (1)

Minwee (522556) | about a year ago | (#43082647)

If you read the article, the official Android documentation is nothing but an ad for Stack Overflow.

First they should try to use the documentation. (0)

Anonymous Coward | about a year ago | (#43081995)

Once the programmer has to use his/her own documentation, then it'll get better.

It's not the the docs are bad or not used (5, Insightful)

Megahard (1053072) | about a year ago | (#43081999)

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:It's not the the docs are bad or not used (3, Insightful)

phantomfive (622387) | about a year ago | (#43082319)

When you follow the API and your program doesn't work,

That's a pretty good indication that the docs are bad

I'd go further... (1)

KingSkippus (799657) | about a year ago | (#43082479)

I'd go even further, and say that most of even the best documentation doesn't provide use cases and best practices. Picking on MSDN as an example, there are some really good articles out there about various topics, but there aren't a lot of articles on addressing a specific question or need. If you need to know how to use, for example, a treeview control, MSDN is probably the best place to go. But it doesn't answer the question, should I be using a treeview control to begin with, or are there other solutions that might be better? Or, I'm having a specific problem with a treeview control, such as getting it to work right in a multithreaded application. How do I fix this? For those kinds of issues, you don't particularly need documentation, you need a community that is ready and willing to help you.

Having said that, one problem with StackOverflow is that it's not maintained that well. I've frequently found answers there that were just plain wrong, and answers that might have been applicable in 2005 when the software I'm working with was six versions behind what I'm using now. It would be nice if they had some sort of cleanup mechanism to maintain a bit of freshness to the answers and encourage people to re-answer questions when underlying technologies or software changes.

That's why I like(d) PHP docs (5, Interesting)

kompiluj (677438) | about a year ago | (#43082611)

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 [php.net] or there implode string function [php.net] ). 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).

Useful documentation is rare (3, Interesting)

us7892 (655683) | about a year ago | (#43082001)

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

Useful documentation is rare.

Re:Useful documentation is rare (1)

Bigby (659157) | about a year ago | (#43082695)

I see a lot of documentation, but most of it is useless. I don't care about the package structure or class diagrams. I can generate those on my own if I need them. I want a high level description of what was trying to be accomplished and why certain paths were chosen to solve the issue. That includes why other paths were not chosen.

As far as API documentation...it is the best form of documentation around the development world. At least it gets to the point...parameters, exceptions, and return values. For something like JavaDoc, package-info.java needs to be used much more often.

However, use cases are best searched for online. Optimally, all use cases are documented and regression testing executes them during every deploy. That way all problems, or potential problems, have an example. That would be optimal, but never really happens. Not unless a company and the developers are willing to spend the time to cover all the bases.

Stack Overflow is WIN (0)

Anonymous Coward | about a year ago | (#43082011)

I've found a lot of good information there.

I feel bad that I never contribute.

Learn to read documentation? (0)

Anonymous Coward | about a year ago | (#43082013)

I think so many minute details are skipped by using sites lack stack overflow.

I learned to program unix by reading complete man pages from a BSD system, and then following that up with the documentation from the open group. If I'm going to use any library in a project of significant importance, to me or my employer, I'll read what the official documentation has to say - if available.

Reading documention is a skill, just as important as being able to use a specific technology in your code.

Re:Learn to read documentation? (0)

Anonymous Coward | about a year ago | (#43082451)

The downside of course is that it takes a **load of time to read the documentation and for the most part is a complete waste of time and effort. Why someone would spend literally several hours reading the documentation trying to figure out the reason his code is failing under some obscure combination of settings while having a handy repository of users asking the same question and getting the correct answer is plainly stupid, period.

Re:Learn to read documentation? (2)

jkauzlar (596349) | about a year ago | (#43082603)

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

Vetted Examples (4, Insightful)

imnes (605429) | about a year ago | (#43082019)

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.

Not just StackOverflow... (1)

Anonymous Coward | about a year ago | (#43082025)

but from google. When I have a problem, 9 times out of 10, I will google the specific stack trace root, or the problem, and most of the time, StackOverflow is the first result.

USING IT AS MUCH AS 50 % OF THE TIME !! (-1)

Anonymous Coward | about a year ago | (#43082027)

IDIOTIC article !!

PANDERING to the idiot !!

This is NOT INFOWORLD !!

Information Aggregation (2)

BradleyUffner (103496) | about a year ago | (#43082039)

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.

Have a working bit of example code for everything (1)

WillAdams (45638) | about a year ago | (#43082051)

My biggest problem when trying to puzzle out how to do some bit of scripting is that there will be a huge wall-of-text, but no working minimal example of code.

Given things like scripting rounded rectangles in a certain Adobe application being broken 'cause of a trailing space, one wonders if the developers could even create such.

most doc sucks if it exists at all (0)

Anonymous Coward | about a year ago | (#43082053)

Especially for open-source libraries and languages. If the doc exists, it's often out of date, or incomplete with only the simple stuff documented. The examples and smaple code cover only the most trivial usage. We're left to either dig deeply into the implementation, or search the web for something similar. I would contend that a good developer is 10x effecient in googling, not just in code production.

Unruly mashups? (3, Insightful)

six025 (714064) | about a year ago | (#43082055)

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.

That's why Qt is awesome (1)

jacksonic (914470) | about a year ago | (#43082063)

It does the job, but over and above that Qt has excellent and thorough documentation. Trying to move to other frameworks can be frustrating when their docs are terse or missing entirely.

Unruly mashups? (3, Insightful)

oji-sama (1151023) | about a year ago | (#43082087)

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?

Use of Stack Overflow != Bad Documentation (5, Informative)

HaeMaker (221642) | about a year ago | (#43082099)

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.

Re:Use of Stack Overflow != Bad Documentation (1)

wvmarle (1070040) | about a year ago | (#43082373)

I second that.

From my personal experience, a great example would be the MySQL documentation. Those docs are very complete, all possible commands and options are given, but as a result it's also often totally unreadable to me - those SQL reference parts are about as readable as a line of Perl, or a regex. Yet it's needed, and often does give the info I need.

Python docs are much more readable (the module documentation at least; the language reference is too technical and not needed for normal programming tasks) but also sometimes lacking, particularly on examples. But then you can't expect the official docs to have examples for everything.

To get started, sites like stackoverflow with their real-world examples do the job very well. And it's really rare to have a question that's not already been asked before. And of course useful to find out that you're hitting a bug...

Re:Use of Stack Overflow != Bad Documentation (1)

cstdenis (1118589) | about a year ago | (#43082597)

Also API documentation is often only useful if you know the name of the API you are looking for.

If what you want to know is "How do I do X?" or "What API do I need to use to accomplish X?" and most importantly, "What is the best/most efficient way to do X?"

Pass over (1)

stupor (165265) | about a year ago | (#43082105)

I generally pass over links to Apple documentation in favor of Stack Overflow links when researching iOS issues. I always feel like I'm saying "Just get to the point" when I read Apple docs...

Re:Pass over (2)

godrik (1287354) | about a year ago | (#43082415)

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.

Desperate times require desperate measures (0)

Anonymous Coward | about a year ago | (#43082123)

When you're in a jam, sadly, it's not the means, but the end that matters. Instead of navigating the swamps of official documentation, I lookup stack overflow on any given day. Saves me helluva time & effort.

Documenting is not sexy... (1)

sinij (911942) | about a year ago | (#43082173)

Writing documentation is not sexy, or sometimes even rewarded/measured as a productive activity. Good documentation also does not easily translate into sales pitch and does not directly result in higher revenues.

Writing documentation is very important for lowering learning curve and increasing your product adoption. Start explaining this to your decision makers. You can probably sell your product without documentation to organizations that have to have it to function, but for anyone else - it matters.

As to obligatory car analogy. Imagine you are selling cars to a group of people that don't know how to drive. Your competition has Ferrari and you are selling Corolla - at the same price. The only way you can succeed selling Corollas in such situation is if you also make it easy to learn to drive Corollas.

Re:Documenting is not sexy... (0)

Anonymous Coward | about a year ago | (#43082571)

If your car analogy was a car, it would be marked down for having a ding in the fender.

The Google factor (1)

PseudoCoder (1642383) | about a year ago | (#43082179)

I would say most inquiries are motivated by wanting to achieve a specific technical task/goal. (eg. Get working directory C++ ). When developers enter their search queries, it's in the form of a question and the first results that come up (in my experience) are Stack Overflow entries. Official documentation is setup more like a technical reference often with only a few less than-practical examples, or examples that don't exactly fit the context of the specific technical task/goal you happen to be pursuing at the time.

I like the thorough technical reference for when I need to know all the available options and parameters, and related topics. Sometimes documentation sets also come with examples that exercise many of the practical development scenarios that closely match the developers' goals. The documentation for the toolkit I'm currently using (LEADTools) is a pretty good example of that. Otherwise if the people writing the documentation are not practical developers they may not be able to write a good enough set of use cases and examples to complement the technical reference well. So you open up a browser and search and there is pretty much the exact same question you're asking, answered in about 2 or 3 Stack Overflow entries, with suggestions, debates, links to other references, etc. Often times it's what you needed and a little more. And off you go...

Actual usage (2)

Todd Knarr (15451) | about a year ago | (#43082197)

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.

Good doc writers can't code (1)

badford (874035) | about a year ago | (#43082239)

and good coders can't write docs.

They are different things. VERY DIFFERENT THINGS.

One is DOING, the other is TEACHING.

I confess (1)

futhermocker (2667575) | about a year ago | (#43082289)

Most of the times I end up at SO through the google and in over 50% of all "cases" that helps more than ploughing through documentation pdfs, wikis and kbs.

Even though I am a documentation evangalist as part of my job, I believe documentation will never get better and will always be incomplete.

Good, or at least, good enough documentation saved my ass numerous times. For example documentation about a custom compiled database function that got lost because somebody, dropped the database instead of the table as intended. A binary restore from a backup got the data back, but the function was lost. The application using the function failed instantly. Although I wrote the function myself, it would have taken days to rewrite it from scratch. Luckily I documented the function code and how to load it, and a smart coworker managed to restore it without consulting me.

Documentation is an ambiguous beast, too little is bad, but too much is sometimes worse...

Re:I confess (0)

Anonymous Coward | about a year ago | (#43082589)

...I believe documentation will never get better and will always be incomplete.

No "belief" necessary - you're right.

I worked for a very large IT company that was one step behind HAL. They hired contractors to do their documentation. All the contractors did was copy and paste the function headers from the developer's comments - ex. 'DasWriteFile' "Pass in pointer and write date to file.". One guy actually published his shit in a book and got a bonus from his dipshit contracting firm - named after the founder who was full of shit but made millions because he could schmooze really well - he worked for them. Yes, the OS that was sold by that company one step behind HAL didn't give a shit about documentation.

The outside developers knew more. As a matter of fact, the 'bible' among the kernel devs inside the company was a red book written by a non-non-HAL person - Keitel or something.

Says something when internal people are using external docs.

2/3rds of documentation is dead space, you failed (1)

Dan667 (564390) | about a year ago | (#43082327)

really, is it that hard to understand when you bloat your documentation to be mostly useless headers, etc for who knows why people are going to chuck it like a paper copy of the phone book?

How about actually trying to get it right? (4, Insightful)

Bill Dimm (463823) | about a year ago | (#43082443)

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 [microsoft.com]. 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.

Re:How about actually trying to get it right? (2)

Bill Dimm (463823) | about a year ago | (#43082653)

Also, whenever function arguments are of some #define'd type (e.g. DWORD, LPSTR, SQLHDBC), those type names should all link to some explanation of what they are and how to appropriately generate and use them (e.g. how to do conversions between all of the different string types) so developers don't have to go on a long expedition to find out how to set up the inputs for a function.

MSDN Documentation just Sucks (1)

medv4380 (1604309) | about a year ago | (#43082445)

I'd love it more if I could just go to google or bing and put in the API name I'm using and have it pull up a good readable documentation, but the search engines can't parse their Docs well enough to figure out it's the authority on the API so what chance does a person have of understanding it. OTOH I can type an API for Java like StringBuilder and it usually comes up with the Official documentation first. As bad as java can be javadocs do cover most of what needs to be documented without being too hard to read. It would be nice if things like C,C++ and all the other languages had a standardized way of documenting, but they don't. Developers choose not to document properly even when they have good example to follow, and that leave only the crowd of the web as the best alternative to looking up the programmers in the basement until they come out with readable docs.

Perhaps it's Give Me The Codez? (4, Insightful)

tlhIngan (30335) | about a year ago | (#43082499)

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.

No surprise there (0)

Anonymous Coward | about a year ago | (#43082527)

When searching for a given API name these sites tend to show up higher in the search result then MSDN.

What would I do without the web? (1)

SecretSquirrel33 (1857738) | about a year ago | (#43082535)

As a younger developer (~5 years) I often wonder what it was like to be in the industry 25 years ago, before the web is what it is today. Documentation is ALL online. I only read software books for academics or to learn something new. In order to get the job done, there is no substitute to google and/or sites like stack overflow.

Obvious result... (1)

Bill, Shooter of Bul (629286) | about a year ago | (#43082555)

Not surprised. This is one of the things that separates really bad developers form okay ones. The ability to research a problem. There are many cases of stack overflow answers not being comprehensive. Often I've found developers arguing that there is a bug in another section of the code, due to a stack overflow answer. Consulting the original documentation would have revealed the subtle edge case that explains the behavior.

Do you use a dictionary to write an essay? (4, Insightful)

Overzeetop (214511) | about a year ago | (#43082605)

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.

This isn't new (1)

ArhcAngel (247594) | about a year ago | (#43082615)

Wasn't this one of the primary uses of IRC/Gopher/Telnet/eMail/listserv back in "the day"? I know that's the only way I would have ever gotten NT 3.51 installed on a few of my systems. I had 4 identical machines but the memory timing was off on 3 of them just enough to give the NT installer fits. Ended up turning off caching to get it to install. It took 8.5 hours but it worked. Once installed re-enabled caching with no problem.

That's because the vendors do a lousy job (1)

dpbsmith (263124) | about a year ago | (#43082625)

I loved the VAX/VMS documentation. It was complete and it was accurate. I loved the original Inside Macintosh documentation; it interesting because it was complete, accurate, and _knowledgeable_. It took helpfully opinionated stances, like "Usually, you will set this argument to nil," or "Returns an integer value of 0 or 1. Only the Shadow knows why it is an integer rather than a boolean."

A couple of years ago I needed greyscale images, nothing fancy but using color was just silly, and wasted over a day trying to get Microsoft .NET PixelFormat.Format16bppGrayScale to work. It kept throwing exceptions and I was just going nuts, unable to figure out what I was doing wrong. Eventually I Googled, and found three-year-old forum postings explaining that Microsoft had never implemented that functionality. But in three years, they couldn't be bothered to remove it from their symbol tables or to update their documentation to at least indicate that it was "reserved for future implementation" or something.

Look for yourself: the online documentation still shows it as available [microsoft.com]. "The pixel format is 16 bits per pixel. The color information specifies 65536 shades of gray."

Mac OS X is just as bad. The so-called documentation looks and feels as if it were automatically built from header files.

Forum postings and crowd-sourced chatter is great--it's where I learned what I needed to know about PixelFormat.Format16bppGrayScale--but it's not a substitute for documentation. And, by the way, neither is sample code--it is valuable in show what works--or worked at the time it was written--but it does not show you the limitations or the boundaries, and nobody takes any responsibility for its future accuracy.

PHP Manual, online version (1)

Fencepost (107992) | about a year ago | (#43082637)

Offhand I can't think of a better example of doing it right than the online version of the PHP manual. The user contributed notes make a huge difference in dealing with real-world usage.

Examples is key (0)

Anonymous Coward | about a year ago | (#43082639)

For any language, API or framework ... the strength of the documentation is only as strong as the examples provided. Most places have a very small examples that often to not lend themselves to real world problems people face using the technology.

Narrow vs broad (0)

Anonymous Coward | about a year ago | (#43082657)

MSDN and the like are excellent resources of very narrowly-focused technical documentation. You want to find out exactly how to use a function? It'll be there, in great detail, giving you all the information you require. Sometimes this is all you actually require, such as when you want to ensure you're sending the correct parameters, understand the error codes, etc etc etc.

However, what that kind of documentation generally doesn't tell you is how to combine the different language features/API/etc to achieve your goal. Sometimes the issue isn't understanding the in-depth details of a function, but rather not knowing what function(s) to call to do what you want. This is where Stack Overflow, various coding forums, etc come into play. Ask a question (after spending some time with the search tool of course!), get the answer. With these problems, the big issue is know *what* functions/features are available rather than how to use them.

Once the explanation is given, the original poster will (I'm assuming) have learnt something new. "What's this new function? That looks useful. I'll look into that later." And thus they can delve into MSDN and the like to read up on this wonderful thing they just discovered, and follow appropriate topics to expand their knowledge.

Technical documentation supports community support sites, and vice-versa. IMO bad programmers learning something new will use one, good programmers will use both (search to see if the topic has arisen before, see the suggested solutions, and then look into them in far more depth to see which ones are appropriate and understand WHY they are appropriate).

Stack Overflow's website is also very efficient in terms of run speed and displaying the relevant answers. For the latter, the self-moderating community can take all of the credit for that, as the post voting system doesn't seem to be abused at all.

php does documentation best (1)

gr7 (933549) | about a year ago | (#43082665)

Don't flame me because you think php is a bad language. I'm just saying it has the best documentation out there. It's on the web and each piece has good examples and then - most importantly - anyone can comment below for each function and feature - issues they've run into. The kind of stuff normally found on stackoverflow. I've been programming since everything was paper (the computers printed on paper only, and the documents were all on paper). I love paper docs, but online, editable, wiki like documents are the best.

Trust the crowd.

Google is my man (1)

stanlyb (1839382) | about a year ago | (#43082667)

Really, why the frack should i spend 1day of reading all the library's API, understand how it works, read the examples, and do some by myself, and then writedown 5-6 API calls, and....forget about it, if all this unnecessary work is already done by some one else, and GOOGLE has him framed, i mean indexed :D. So, why not just use the existing knowledge, do my job in 10min, and move on!

My Microsoft Interview (1)

Anonymous Coward | about a year ago | (#43082681)

I once went to Microsoft in Dublin around 2005 for an interview as a web developer. It was a consultant position for an agency, and they had a guy meet me 10 mins before to coach me on what answers they wanted to hear from me. The agency guy was actually in the interview room beside the guy asking me the questions. I had a good knowledge of the technology and answered all the questions as well as anyone could... except for one apparently...

"if you are programming something, and you get lost or stuck, how would you go about overcoming the difficulty and finding out the correct way forward."

I answered:
-I keep extensive notes/code from my training and previous work for reference
-I contribute to many online forums and communities and am well respected, people quickly offer insightful answers to any questions i raise.
-I refer to e-books and online documentation specifications
-I have many friends in the tech industry that specialise in various areas and languages, I have a go-to guy for almost any area I could be stuck on.
-I refer to available colleagues and co-workers if I have exhausted several avenues and time is a factor.

The guy looked at me like I had 2 heads! and the guy who coached me looked at me like I was nuts...
"any others?"

I elaborated a little more on my answers above, but they looked disappointed with my answer and quickly brought the interview to an end.
The manager asked the other guy (who coached me) to show me out. It was as if I had pulled my dick out in the middle of the interview.

We quietly walked to the lift, got in and he pressed the button for the ground floor. as the lift moved the guy broke the awkward silence:
"The answer was books!" he said. I stood there stunned for a second before the doors opened, he didn't even get out of the lift "door's over there"

And that was that. It's the only job I'm glad I didn't get. The interview was for me a first-hand look at the rigid minded, controlling, tick-box nature entrenched the organisation from Steve Ballmer downwards. Perhaps they are different now for their senior developer hiring practices since they face competition from the likes of Apple, Google, Facebook and a hundred other high tier tech companies, but from my observations and reports from friends who work there since, I doubt it.

Load More Comments
Slashdot Account

Need an Account?

Forgot your password?

Don't worry, we never post anything without your permission.

Submission Text Formatting Tips

We support a small subset of HTML, namely these tags:

  • b
  • i
  • p
  • br
  • a
  • ol
  • ul
  • li
  • dl
  • dt
  • dd
  • em
  • strong
  • tt
  • blockquote
  • div
  • quote
  • ecode

"ecode" can be used for code snippets, for example:

<ecode>    while(1) { do_something(); } </ecode>
Sign up for Slashdot Newsletters
Create a Slashdot Account

Loading...