Developers May Be Getting 50% of Their Documentation From Stack Overflow 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?"
Documentation Shitty so Developers Turn to Web (Score:5, Funny)
News at eleven.
Re: (Score:3, Insightful)
Re:Documentation Shitty so Developers Turn to Web (Score:5, Interesting)
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 (Score:5, Insightful)
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: (Score:3)
Re: (Score:3)
I thought Stackoverflow was the official documentation?
In all seriousness, when I have a choice between two links, and one is the documentation and the other is SO. I choose SO first. Then check the documentation for the nitty gritty details.
Re: (Score:3)
The best usage for StackOverflow answers, in my opinion, is basically as a "see also" cheat sheet. Phrase a question in English, with details, in Google and you might find one already there. Else, post it and someone will give an answer with the magic words to follow up on.
Someone wanting to learn about security in Windows might not know what a token is, a casual DBMS user might not realize Oracle can do tree walks with some very non-standard SQL without having to write stored code, someone might not know t
Re: (Score:3)
The number one thing I end up on StackOverflow for is Win32 API, which you don't list. There's a few good references out there, but not really any good "official" references. MSDN helps understand everything on a deeper level (more than sometimes deceptively), but it's just not realistic at several points compared to looking on StackOverflow and other sites along those lines. Furthermore, there's several elements of the Win32 API, the best reference that I find is from StackOverflow.
Otherwise (maybe a coupl
Re:Documentation Shitty so Developers Turn to Web (Score:5, Insightful)
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.
Fuzzy searching (Score:3)
Microsoft (et al) are good for answers to questions like:
how does (x) work (what are the details of (x) )
Stack Overflow is good for answers to questions like:
how do I do (x).
Really, really, really different types of questions.
Re: (Score:3)
Too much vendor documentation is geared to lawyers, CYA and is needlessly verbose.
Many web sites tell you what it really took to get something going versus how it's supposed to work.
I read a lot of bad documentation. Remember English class where you took a few 3x5 note cards and padded it out to a five page paper? I've read too much vendor documentation that looks just like this. No economy of words.
Re:Documentation Shitty so Developers Turn to Web (Score:5, Interesting)
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.
Re: (Score:3)
Mmmmm, no. Not in my experience.
Often I know exactly what I am going for, which API I need, etc. Google the name, with MSDN as one of the search terms, land exactly on the appropriate MSDN page, read the format, check that I have the required headers, code the call and done.
Most of the time that is sufficient, and it is by far quicker than wading through someone elses verbiage, code samples, 37 replies, 35 of which are unhelpful, etc. etc.
If you understand and use MSDN frequently, it quicker (by far) for t
Afterparty (Score:3)
Google the name, with MSDN as one of the search terms, land exactly on the appropriate MSDN page, read the format, check that I have the required headers, code the call and... ...then you look on StackOverflow to figure out why the call didn't work like you thought it would.
Re: (Score:3)
Re:Documentation Shitty so Developers Turn to Web (Score:5, Funny)
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: (Score:3, Insightful)
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 (Score:5, Insightful)
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: (Score:3)
you sir, have perfectly described it. So well, in fact, that my wangle is, indeed, throbbing.
But seriously - this is probably the biggest challenge I face in my work - which I've been doing since about 1980. When I encounter some documentation, and there's no fucking context, and no reference TO context - that documentation just utterly fails. Here it is. 2013. And we still haven't solved the problem.
I go to Stack Overflow, and read through a few extra pages of chitchat . . . and THERE is my context. Usuall
Blame Google (Score:5, Insightful)
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 (Score:4, Insightful)
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: (Score:3)
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 (Score:5, Insightful)
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 (Score:4, Informative)
http://www.google.com/reviews/t [google.com] is the page you can use to block a site from Google's search.
Re: (Score:2)
..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: (Score:3)
Solution: Stop using IE.
Re: (Score:2)
Re: (Score:2)
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 i
Re: (Score:2)
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? :-)
Re:Blame Google (Score:4, Interesting)
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.
These are two different use cases (Score:5, Insightful)
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 (Score:3)
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 (Score:5, Insightful)
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: (Score:2)
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?
Re: (Score:3)
Well no... but like I said, it should be.
Police should also be unbiased, governments should be fair, and there should be peace and happiness and abundance throughout the world.
Documenting Reality (Score:5, Insightful)
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.
Microsoft docs (Score:5, Insightful)
| 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 (Score:4, Interesting)
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: (Score:2)
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: (Score:2)
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 inst
Re: (Score:2)
And of course, in some cases MSDN has zero documentation for stuff. For example, there's many instances of the Windows Scripting Host functionality where it is only documented in VBScript despite the fact that Microsoft fully supports JavaScript with WSH as well. So you have to turn to other sources to figure out how to do it in JavaScript if that's what you are using. (Yeah, it drove me nuts a few years back.)
So now I use the MSDN search in Firefox, or use the "site:microsoft.com" featu
It's not the the docs are bad or not used (Score:5, Insightful)
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 (Score:4, Insightful)
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... (Score:2)
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 solut
That's why I like(d) PHP docs (Score:5, Interesting)
Re: (Score:3)
MSDN also has user-contributed notes for most doc pages (e.g. open this [microsoft.com] and scroll to the bottom). They do get used occasionally, but not all that often.
Re: (Score:2)
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...
... your own post from 5 years ago asking exactly the same, unanswered, question. *sigh*
Re: (Score:3)
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.
If only there was a clear-cut way to tell Google, "Please hide all of the results that are on a forum with only one post in the thread". My 2nd biggest pet peeve about Googling for answers this way is the huge amount of search results asking the same question I have, with no answers.
My #1 peeve is people taking a crack at answering the question with no understanding themselves about the problem. Answers like "I've never done this myself, but I think blah blah blah" or "Why would you want to do that? Boost
Useful documentation is rare (Score:4, Interesting)
Useful documentation is rare.
Re: (Score:2)
Vetted Examples (Score:4, Insightful)
Information Aggregation (Score:2)
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.
Unruly mashups? (Score:4, Insightful)
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.
Unruly mashups? (Score:4, Insightful)
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 (Score:5, Informative)
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: (Score:2)
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 task
Re: (Score:2)
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?"
Documenting is not sexy... (Score:2)
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.
Re: (Score:3)
Actual usage (Score:3)
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.
2/3rds of documentation is dead space, you failed (Score:2)
How about actually trying to get it right? (Score:5, Insightful)
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: (Score:3)
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 (Score:2)
Perhaps it's Give Me The Codez? (Score:5, Insightful)
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.
Obvious result... (Score:2)
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? (Score:5, Insightful)
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 (Score:2)
That's because the vendors do a lousy job (Score:2)
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 try
PHP Manual, online version (Score:2)
Google is my man (Score:2)
How... (Score:4, Funny)
How should official documentation be better redesigned?
It should exist.
official documentation (Score:2)
In my experience, official documentation tends to fall in two categories:
Category A, the features manual. You can do this, you can do that. You can manage things like this and this. You can setup this to do that automatically. But no word on how to accomplish any of these things, or even what specific named feature to use.
Category B, the reference manual. This feature has these options. This other feature has these other options. This third feature has these options. Each entry is usually accompanie
I use it a lot (Score:2)
Exceptions and error codes (Score:2)
The main reason why StackOverflow keeps coming up for me over and over again is because when I Google for my exception or error code, I get real anecdotal evidence of other people seeing the same exception and then other people helping resolve those exceptions. Microsoft's technet is pretty decent at searching for exceptions/error codes, but typically only show up for older products (i.e. newer products are too recent and not as adopted so less errors are discovered by the community at large) and many time
Re:What does StackOverflow run on? (Score:5, Insightful)
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: (Score:2)
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: (Score:3)
Re:What does StackOverflow run on? (Score:4, Insightful)
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: (Score:3, Interesting)
There are no bad languages, just languages being misused.
Oh so very wrong. [wikipedia.org]
There are even some accidentally bad languages, but of the commonly known languages, yes, they tend to be good for some purposes.
Re: (Score:3)
Baby talk is a great language for certain purposes. But you don't use it in a meeting with your bosses.
You haven't met my boss. Baby talk is by far the most efficient means of communication. I've been known to reward him with lollipops occasionally if and when he behaves himself.
Re: (Score:3)
I'll agree if you specify PHP4. PHP5 can be used responsibly.
Re: (Score:3)
Why change it if it still does what the company needs it to.
This brainwashing we are experiencing that we need to update everything all the time...is hogwash!
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???
Re:What does StackOverflow run on? (Score:5, Insightful)
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.
Astroturfing Detected (Score:3, Insightful)
All or nearly all of your comments are pro-Microsoft and anti-Microsoft competitors.
Re:Astroturfing Detected (Score:5, Funny)
Don't worry, he's just making sure none of us get Scroogled.
Re:Astroturfing Detected (Score:4, Interesting)
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:Astroturfing Detected (Score:4, Funny)
That kind of depends on what help you need. For example, if you are looking for some facial feminisation surgery, you may find what you need at expertsexchange.com.
Re: (Score:3)
Re: (Score:2)
Re: (Score:2)
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: (Score:3)
Re: (Score:2)
Lets pick on the few folks who don't believe in the Microsoft = automatically bad and Google = automatically good mantra, and lets chase them away calling them shills and astroturfers. And let the groupthink and echochamber rejoice. Eventually the haters and zealots get bored talking among themselves and they leave and you get an ever shrinking website with even more partyline moderation.
Re: (Score:3)
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.
Re: (Score:2)
Re: (Score:2)
Re: (Score:3)
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.'
Re: (Score:2)
If your intent was to say that being a good developer doesn't automatically make you a good tech writer (and the inverse), then I'd agree. But doing one well doesn't preclude you from doing the other well.
Re: (Score:3)
Mod up. That is how I end up on the code project and stack over flow. My most recent task is:
How do I send a client certificate with a POST request from c#? First time I've had to do any of that.
So I use some basic google-fu turn that into a sensible keyword search and you get a few examples from forums, including stackoverflow.com, support.microsoft.com, forums.asp.net, c-sharpcorner.com, etc.
Its not until about halfway down page 2 of googles search that I get ANYTHING from MSDN. And when I do its an artic
Re:What would I do without the web? (Score:5, Funny)