Slashdot Mirror
Developers May Be Getting 50% of Their Documentation From Stack Overflow
New submitter gameweld writes "Software companies, such as Microsoft, create documentation for millions of topics concerning its APIs, services, and software platforms. Creating this documentation comes at a considerable cost and effort. And after all this effort, much documentation is rarely consulted (citation) and lacking enough examples (citation). A new study suggests that developers are increasingly consulting Stack Overflow and crowd-sourced sites over official documentation, using it as much as 50% of time. How should official documentation be better redesigned? What are the implications of software created from unruly mashups?"
News at eleven.
It's better to vote for what you want and not get it than to vote for what you don't want and get it.
- E. Debs
Whenever I have a problem, I google it, and StackOverflow is always in the top of the results. If Microsoft want me to use their documentation they better make sure google indexes it in a way than matches my queries.
Documentation and asking others for help when you get stuck complement each other. You can't really learn to use something completely new on Stackoverflow, and you can't predict all the ways people will screw up or misunderstand you in a documentation.
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).
"First they came for the slanderers and i said nothing."
How is this anything other than an ad for StackOverflow?
Once the programmer has to use his/her own documentation, then it'll get better.
The problem is lack of usage examples and feedback. When you follow the API and your program doesn't work, the solution is to google your problem to find the solution from the 1000 others who have hit the same problem.
I eat only the real part of complex carbohydrates.
Useless busy-work after-the-fact documentation is overrated and plentiful.
Useful documentation is rare.
I've found a lot of good information there.
I feel bad that I never contribute.
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.
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.
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.
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.
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.
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.
Sphinx of black quartz, judge my vow.
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.
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.
All or nearly all of your comments are pro-Microsoft and anti-Microsoft competitors.
It's better to vote for what you want and not get it than to vote for what you don't want and get it.
- E. Debs
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.
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.
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?
It is what it is.
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.
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...
Do you inspect a roller coaster everytime you ride it?
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.
"There is more worth loving than we have strength to love." - Brian Jay Stanley
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.
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.
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...
"Now, I doubt any of you would prefer a rolled up newspaper as a weapon against a dictator or a criminal intruder."
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...
Reddit on PHP?
Have you been living under a rock or something?
The source is on Github, dude.
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.
and good coders can't write docs.
They are different things. VERY DIFFERENT THINGS.
One is DOING, the other is TEACHING.
-badford
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...
KERNEL PANIC -SIGFAULT AT ADDRESS #51A54D07
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?
VB6?! You had to reach pretty far back for that reference. You might as well throw in RPG while you're at it.
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. 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.
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.
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*
Self proclaimed typo king, and inventor of the bear destroying coffee table (patent not pending).
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.
Sorry, but PHP is a better example of a bad language than VB6. Not that VB6 was good... but PHP is far worse.
"I will trust Google to 'do no evil' until the founders no longer run it." Hello Alphabet.
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.
Someone downmod this $hill linfaggot
When searching for a given API name these sites tend to show up higher in the search result then MSDN.
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.
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.
Well.. maybe. Or Maybe not. But Definitely not sort of.
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.
Is it just my observation, or are there way too many stupid people in the world?
In PHP docs with every item there comes the section for for "user contributed notes" which are sometimes pretty insightful (like there php strings intro or there implode string function ). Long time ago in a galaxy far away when I used to code in PHP those useful comments not only usually saved my day, but somehow compensated for the unorthogonality (well, an understatement) of the PHP standard library and the language itself. So - yes - I definitely prefer using worse language with better docs than the other way round (think Haskell vs PHP).
You can defy gravity... for a short time
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.
"A person is smart. People are dumb, panicky dangerous animals and you know it." - K
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.
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. "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.
"How to Do Nothing," kids activities, back in print!
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.
fencepost
just a little off
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.
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.
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.
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!
How should official documentation be better redesigned?
It should exist.
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.
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...
When I look at documentation, I usually see a longlist of gibberish that I can't cram into the misshapen jigsaw puzzle that is my ne'er standing of any given language. I see a long list of obtuse methods and properties that are generally more related to language structure itself than they are to the intended usage of the class question. I've loaded a page hoping to find out if the Arrau class has a built-in method for removing an object from and arbitrary index, but instead I'm learning that the Array class has a method that sets a flag that tells the Array to treat all Ints as Uints to maintain compatibility with something that people stopped using when I was busy playing with HyperCard.
As a slow-poke, I like examples. When I read an example, I like it to tell me if I'm going to need to include so e other random header to make it work, even of it's extremely obvious to someone who knows what they are doing. Because I don't.
I don't need to know that yes, this class can duplicate itself in a seldom-used way, just like like twenty other objects above it in th chain of inheritance. I need to reada short story about some other idiot who fucked it all up in the same way I did, and fixed it by doing x, y, and z.
So, my two recommendations are, More Examples, and instead o flisting everything alphabetically, sort the methods and properties into categories, like "Functionality the Class was Esigned to Accomplish" (add an item to an array), "Shit you may have to fiddle with if you're doing anything worthwhile" (return an array's contents as some other list-type object), and "what the fuck is this even for?" (If I could come up with a coherent example of this, I wouldn't be complaining about documentation on the Internet, but it's like, 90% of all Microsoft documentation, 30% of all Appledocumentation, and 100% of all Java documentation.)
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 accompanied by a description a third grader could have written: "The blerbfrobinator command is used to frobinate blerbs." Oh, thanks. That made things so much clearer.
It's not just a lack of examples, although examples do help. It's (a) the missing connection between capabilities and individual named features, and (b) some holistic idea of how the product is intended to be used. Best Practices helps in this area, if they are well enough written.
Interpretation of error messages are often completely unhelpful. Explanations are usually just a rephrase of the error message that add no insight. This is where forums come in. Whatever problem you've run into, some group of people have probably had the same problem, and some subset of that user base has written about it somewhere. The trick is to find it.
Parenthetically, Fudd help you if you try to get help from official sources and your problem is not officially recognized as a problem by the vendor. In that case, even when a fix exists, the official techs may be forbidden to give it to you. There again, forums can provide help that you can't get anywhere else.
And finally, the search engines on vendor support sites so often SUCK. When I worked for a very large company, I was responsible for best practices documentation, and I couldn't find a damned thing with the company's own search engine. I had better luck putting the same entry in Google and looking for hits from my company's website.
Oliver's law of assumed responsibility: If you're seen fixing it, you will be blamed for breaking it.
The official android documentation can be really dire, and so is the documentation for OpenGL ES (in general and android specifically). I usually find myself googling the answer and usually Stack Overflow or one of its sister sites is at the top of the results pile.
Perl is the best example of a usable language with bad syntax.
($l=join("",))=~s/.*\n/index($`,$&)>=$[||print$&/ge;
Need I say more?
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 times for only their flagship products. When I do get a search result that links to the vendor's documentation, it's typically just a page that lists all the possible exceptions/error codes and gives no information about what they mean or how they are encountered.
So bottom-line, if documentation writers included good documentation of exceptions and error codes, fewer people would have to submit questions to StackOverflow.
Microsoft is great at churning out tons of information on their libraries and tools. But, so much of it is incohesive. I've had several projects working with their tools and it's like slogging through a swamp. Lots of content, but there's often no clear path through it; not a clear beginning or course to follow. Just page after page, sublink after sublink. It makes their bigger tools look like a handful of granules. Microsoft makes some amazing products like Visual Studio, I just wish they'd make them easier to work with for developers and extenders.
I swear to God...I swear to God! That is NOT how you treat your human!
You joke about RPG, but at my first gig out of school I worked in RPG/AS400 at a series of local casinos (Reno/Las Vegas). I was in one the other night, popped in and lo and behold the system had not changed. Legacy code does not go quietly.
"Never let your sense of morals prevent you from doing what is right" - Salvor Hardin
... you'd know it suck badly (as in: does not explain how things actually work). Point is, if you read for instance javadocs it is quite usable in explaining what the class does / how it should be used. If you ask MSDN in 99% of the interesting (that is: non-trivial) cases it does not say anything about the specifics or how to actually use/interpret stuff (eg. what does cryptic error message xyz actually mean / what can I do to fix it, and thousands of other such cases).
Leaky abstractions lead developers to consult resources that deal directly with their specific problem with specific solutions that have already been shown to work in practice. Most developers write documentation explaining what their APIs do, which is usually pretty obvious based on service calls, method names etc. When a developer consults documentation it is to find out why something is not working as the original author intended it to.
What documentation needs to be doing and frequently does not is explain its abstractions so that a developer can better identify the underlying problems assumptions based on those abstractions are causing. Maybe your implementation of a LinkList using an array under the cover is horribly optimized for the use I intended for it, if you documentation does not explain how it is working then that leaves 3 ways to find this out:
Most of development is very straight forward. Overall, the bulk of work done for something like XQuery or SQL is very simple stuff. The majority of problems that require an expert to solve have to do with those leaky abstractions, where the problem the class or api writer wanted to make disappear with their magical function is not airtight and the complexities seep through. This is where your expert needs to look under the cover and see what's really going on in order to rectify a problem. If documentation doesn't cover this then frequently the quickest way to find the information needed is to look for someone who has come across this problem before and see what worked for them.
There is no memory shortage. yes I have heard of XFCE. Go away.
For those too lazy to look, but strongly curious. It looks like a lot of python with shell scripts.
Didn't notice anything else in my cursory glances.
Self proclaimed typo king, and inventor of the bear destroying coffee table (patent not pending).
Stack Overflow can't always solve all problems. Many times I have looked for an example of how some piece of Sencha's poorly-documented ExtJs framework works, only to be directed to a Stack Overflow page where someone posted a question looking for the same thing.
I know it can be dull and time-consuming to create examples and documentation, but, really, just linking to the source code does not really explain what a particular class or config option does. If you want programmers to get the most out of your framework, you have to show what can be done with it. If you don't have time to document a feature, why did you bother including it in the first place?
Your fantasies contain the seeds of important concepts.
I really like PHP's doc pages just for this reason. There is the official documentation at the top, with user-sourced additions below it. This way, you get both the theoretical and the practical together.
I really wish other language sites would do a similar thing!
Why is it that whenever someone wants to piss on perl, they come up with examples like that. It's like saying C has bad syntax because the OCCC exists.
Unless I need to figure something out that is so unique I need to dig through the (God awful) crap that passes as official api documentation to figure it out, not only will sites such as Stack Overflow offer examples in abundance by some very knowledgeable people, the theory and reasoning's are of spelled out better than any official documentation you will run across most times. Now, I'm sure at least bunch of people will point out that Stack Overflow leads to a lot of copy-paste code. That very well may true for students and entry level quality programmers. There comes a point where copy-pasting an ArrayList example is no longer gonna cut it in your profession but the advice given definitely applies.
is there some other kind?
LMAO!!!
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???
TechNet and MSDN documentation and associated sites like msdn.microsoft.com/vstudio and asp.net are actually really good and I use them a lot. The problem is that they are not searchable from traditional public search engines or the content scores really low on the the search engine rankings. Most developers first reaction to a problem is to Google it, and 9 out of 10 times the first results are all links to Stack Overflow. That's better than it used to be which was pay gates to Experts Exchange. I won't say that is Google's or Microsoft's problem directly, but I would think it would be in both parties' interest to get better quality documentation to the top of the search results. Microsoft definitely needs to improve the search ability of TechNet and MSDN as well.
The API doc from Microsoft, Google, Apple etc tells you that something can possibly be done. My choice is to either spend hours/days/weeks struggling to figure out how to write the code that uses the APIs, or google it and see how someone else did it. This is resuable code in a way I don't think anyone ever envisioned.
Also, official doc doesn't have error messages. I imagine most of this googling and hitting Stack Overflow is from people trying to figure out some obscure error message. You run something that uses a framework that imports ten other frameworks, and crashes with an error message like: "XML parse error on line 213209: Bean definition is not sufficiently ambiguous for bean com.company.project.group.product.release.version.whatever.DoSomethingGreat (is your constructor big enough?)" And you just copy and paste into Google. Much faster than looking it up. And Google will find actual answers, not just API doc on the class.
I've gotten to where I'm fed up with examples and doc not having the import statements for a Java class. I google "import" "BrainException" and I'll usually hit code that says "import com.company.project.group.product.release.version.whatever.BrainException;" on the page. That is so much faster than trying to find and wade through JavaDoc.
Is it just me, or are man pages for newer program less complete and/or non-existent? For example, Bash has a huge exhaustive complete man page. The only issue is finding information there since the file is so huge. It has examples, describe what all the parameters do, etc.
Report lab, a PDF generator library for Python, on the other hand, has no man page. It does have a PDF document, but that's a lot harder to search or use while at a terminal.
For years now DevHelp (various Linux distributuons) been lacking such a fundamental
as ButtonRight-menu where you can copy/paste.
Reading/browsing documentation I always find myself doing so with mouse-in-hand, so
that kind of popup menu is almost second nature, and it should be just standard in any
GUI. Yet DevHelp developers don't seem to know this. Or simply dont' care, what with
the issue being reported maybe two years ago already by yours truly.
Documentation and origional sourced documentation do not fare well in Google SEO as it remains static and changes little. Google hates this and punishes content which does not change even though it may be the official and often correct documentation. Google favors content which is refreshed often like crowd sourced content. The problem is that it may take the gathering of a dozen or so crowd sourced pages to get the understanding and content I need while the official documentation would give me the full explanation and nuances. I would reather read the official documentation first and then go to the crowd sourced documentation to find a solution to a particualr hicup I'm experiencing. Google amy be marginalizing and ultimately killing official documentation as it will become useless if not ranked. Too often Google will show an entire page of top SERPs all from the same domain and crowd out everyone else. Google should stop playing these SEO tricks and games and really examine the content for how much unique information is presented. Its a tough job but ultimately its what people are looking for.
Funny, I thought stackoverflow was just a bunch of asked / answered questions with snippets of code going back and forth. Very useful ones, and at times very relevant when one is having the same problem or exploring the same concepts as others. (Me I like ozgrid and cpearson.com for Excel issues...)
But you think that is what passes for documentation?
See, there really isn't anything that should be redesigned in official documentation, instead you should learn the difference between documentation that describes x, instead of a list of problems/solutuions/examples about x. There, FTFY.
you poor asp slave
First written in Lisp, then ported to python for maintainability, if I recall correctly.
"Science can amuse and fascinate us all, but it is engineering that changes the world. " - Asimov.
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.
W..w..W - Willy Waterloo washes Warren Wiggins who is washing Waldo Woo.
Perhaps I'm alone, but I find the clutter of StackOverflow posts in any programming related search incredibly annoying. Many of the results aren't relevant and usually the rest contain incorrect, out of date or incomplete information. Give me the docs and the project's bug tracker.
There are no bad languages, just languages being misused.
Oh so very wrong.
There are even some accidentally bad languages, but of the commonly known languages, yes, they tend to be good for some purposes.
The problem with a lot of documentation (including, but certainly not limited to Microsoft's) is the lack of examples. I notice this with Linux man pages too, rarely do functions come with examples, even when the calling and return values may be complex. Defaults, special cases, typical usage... all of these should be documented with examples. That's why I really like the PHP project's style of documenting function calls. The documentation usually includes a few examples and then people can provide comments and their own examples underneath. It makes for a really clear picture of how a function is meant to be used.
I'll agree if you specify PHP4. PHP5 can be used responsibly.
W..w..W - Willy Waterloo washes Warren Wiggins who is washing Waldo Woo.
A lot of the Microsoft API documents contain no actual information. You end up relying on code samples or stack overflow. Sometimes you get lucky and there is community documentation at the bottom it seems ridiculous to have to rely on that. I'm assuming that the API docs are generated from the Class / Method documentation which makes me think they have millions of undocumented lines of code. You see this in Visual Studio when using intellisense. You see some method with 10 overrides and no documentation on how they should be used. It would be great if class docs showed usage. Then that would be auto-generated into the public docs. I worked in the Java space and used to complain that some companies didn't generate decent class/method documentation because their developers don't think it is important. The microsoft space is even worse :-(
Beauty is in the eye of the creator. Your baby (API) is ugly!
When Java first came out, I thought the documentation was extremely good, and a model use of hypertext (I cannot comment on its current state because I no longer use it.) In comparison, Microsoft's documentation leaves a lot to be desired. The pages in the API reference section are very formulaic, oriented towards describing syntax rather than explaining semantics. There is a lot of hyperlinking, but it doesn't necessarily help: you can follow long chains of links from one uninformative place to another - there's no "there" there.
There is some excellent tutorial material to be found on Microsoft's site, by people who clearly both know their stuff and how to communicate it, but it's hit and miss as to whether your current concern has been well covered. These would seem to be good places for the API references to link to, but that does not seem to have been done nearly as often as it should (perhaps the links in the API references are largely machine-generated?)
I get the impression that the overall management of documentation production is driven by objective but superficial metrics, such as the number of pages and links, without regard to qualitative but important considerations such as quality and usefulness. I also imagine that much of the grunt-work is farmed out to masses of asses.
It doesn't help that Microsoft has multiple, overlapping products and APIs, and there does not seem to be an easy way to constrain a search of their sites to your specific domain of interest (unless you are searching for a specific language element and you know its namespace).
I am not an anti-Microsoft partisan, and I am well aware that the documentation in the FOSS word also varies from excellent to execrable. Creating good documentation of complex issues is a hard problem.
this is how it should be. why should i check documentation written by a single entity when i can use a crowd-sourced, peer-reviewed site?
don't get me wrong: documentation is great for questions like "what arguments does x function take?" in that case i'll always go immediately to, say, mdn or php.net.
but for human-oriented questions like "why doesn't x work here?", in general, documentation sucks. it's much better to find or ask your question on stack overflow so you can learn from others' experience.
It used to be that doc was great and good. Thinking borland Delphi 7 and before, Visual studio 2005? and before...
Now days, it's a web interface stuff on MSDN (or other) and it's so loaded for crap that you can not find any documentation that you are looking for.
I actually still have the .hlp files for the win32 API that came with Borland Delphi 7 and that is what I am using rather than the current stuff that comes with Visual studio.
I do simple C/C++, Win32 and the current help is so overloaded with stuff that you simply can not find what you are looking for!
Same for Office, with office 2003, it was easy to find and get help on some obscure Excel function. Nowdays, even if you know the name of the function, good luck.
Cyrille
The problem isn't always the fact that ad-hoc support sites are used in place of documentation, but that ad-hoc support sites change while most documentation never does. There are two factors against documentation: First, these forum websites are updated regularly and so are indexed more readily; Second, software/programming documentation sites are filled with dying documents. Even MSDN is a dying resource. As soon as the next iteration of .NET is released, all documentation for previous iterations of .NET become deceased soon after. In addition to documentation being dead documents, the information in them is rarely improved upon before they do become deceased. Sometimes, the documentation is DOA with a new product because somebody didn't care to update the documentation to support the very similar, new product.
If people cared about their product a little more, maybe they'd make an effort to keep their documentation alive and in shape so sites like stackoverflow would become obsolete, at least to real programmers who don't just use documentation like it were Play-Doh.
What was the point of mentioning MICROS~
AccountKiller
As several dozen other people have mentioned crappy docs account for a lot of it, the fact that Stack Overflow comes up first in most searches is a lot more of it, but another factor is that, in most cases, devs aren't looking for a technical definition of some API method. They are looking for a solution to a problem and the way technical docs are written they don't lend themselves to those sorts of questions unless you know the method that you need and can go right in there and find it.
And then hope that it has some sort of readable description and possibly an example. Otherwise, it's off to what ever site actually has a post by some who has used that method and can tell me how to use to solve my problem.
A while ago, I was looking for something to fill my time with. I thought, hey, I enjoy using Wine to use certain Windows programs on Linux, and I'm not terrible at coding, I'll pick a bug or two and see what I can help with. I downloaded the source code, and quickly got lost, as the source ode is essentially undocumented, with no comments anywhere. When I looked for help, I found out that the people who write Wine code expect you to go to use Microsoft's official online documentation as your main, if not only, source of help. So they want you to depend on Microsoft to have perfect documentation, but there are practically no comments for why a programmer did something somewhere for what reason in their implementation of Microsoft's API. I found the whole mess too thick for me to bother with and found something else to work on. So congratulations Wine, you drove off a not-that-terrible coder.
That being said, the combination of sucky documentation and a great community of experienced, helpful people seems to work. It'd be great not to rely on the kindness of strangers, but, well, I'd like a pony, too. If there's a magic solution which reduces the prodigious amount of work required to address the issues I pointed out, then I welcome it. But I don't have such a solution handy; if I were a betting man, I'd suggest that the current hybrid solution will continue for some time to come.
The CB App. What's your 20?
My gut tells me that Reddit gets far more traffic then Stack Overflow.
> 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.
Look, no one has criticised your precious .NET, now go away ...
Define good and bad. Novice programmers generally fare better in more restrictive languages like C or Java. On the other hand, an experienced hacker can do amazing stuff in a powerful language such as C++.
Maybe the new bike is lighter and faster, more comfortable, and has more reliable components. Perhaps it's even more sturdy so that I don't have to true my rims every time I hit a pot hole.
No software is perfect; there are always things that can improve. The GP poster doesn't say what the time frame was between coding and seeing it still there, but I wouldn't be surprised to hear that 20 year old code was still sitting there, and that any issues with the code were being dealt with via band-aid pre- and post-processing systems tacked on. Why would they tack things on like that? Because nobody wants to work on legacy code.
The CB App. What's your 20?
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.
"There is more worth loving than we have strength to love." - Brian Jay Stanley
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.
"There is more worth loving than we have strength to love." - Brian Jay Stanley
How should official documentation be better redesigned? What are the implications of software created from unruly mashups?"
* if there is something in the documentation that I don't understand, I should be able to ask questions about it
* somebody should answer basic questions within 1 or 2 minutes
* complicated questions should get an answer within a day or two
* really complicated questions should spark a discussion that is eventually answered
* my question and the answers should be attached to the documentation
* if I see a mistake in the documentation, let me fix it. don't ask me to email someone about the issue, just let me fix it
* if a quick search doesn't reveal the documentation or past question I'm looking for, I should be able to ask about that too and someone will tell me where it is within a minute or so. This exchange is also public, so that my wording of what I'm looking for can easily be found by others who are trying to find the same thing
* there should be some system in place to eradicate spam and crap questions/answers
Alternatively, they could just continue what they're doing and read stack overflow. Perhaps some of their documentation budget should go to hiring people to browse stack overflow and answer questions/generally improve things.
It is a great language for the purpose of which it was created. And it wasn't created for productivity.
I use StackOverflow pretty much daily. For the developers in my company it has become the go-to-source for us. Now (for quite a while actually) StackExchange (the parent site for StackOverflow) has opened up Area51, a place where you can propose your own "stackoverflow" for your favorite topic.
For instance, I work in the Healthcare IT world, so I started this:
http://area51.stackexchange.com/proposals/51758
It's a proposal for a site that focus on things like HL7, EMR integrations, Laboratory Information Systems, Mirth, Cloverleaf, etc... I think it will be a great resource.
Take an arbitrary list, and output a sorted liste with no duplicate entries. You could (still quite tersely) do the same thing with a much more readable:
my @outputarray = sort grep( ( ($h{$_}++ == 1) || 0 ), @inputarray );
Or, you could iterate through using a foreach or while loop, assuming you also understand the memory implications of doing so, and are okay with the possible high memory usage.
But I'm confused - are you suggesting that this would be considered "good" (i.e., maintainable) Perl? Or are you suggesting that it's impossible to write similarly obtuse code in another language?
A decompiler is sometimes the only or best documentation.
That's the thing, on StackOverflow you may well find someone who has decompiled and reconstructed something hard to understand. StackOverflow is like the mechanical turk of API documentation repair.
"There is more worth loving than we have strength to love." - Brian Jay Stanley
I use stack exchange often. It's very very helpful.
You just called Aaron Swartz a shitty coder.
I am a Perl fan and kernel hacker. I love both Perl and C. Perl makes obscurity easy. Easy makes things commonplace. Thus people like the AC above are handed a tangled skein, and endure enormous pain in unknotting it.
My Perl looks like C with a few syntax errors. It takes twice as many lines as "cool perl" and won't win any "cleverest line of Perl" contests, but the counter argument to the GP would seem to be: "Why do people still code in obscure, compacted, uncommented styles?"
Now don't accuse me of being a shill - I'm not. However, I find Apples iOS documentation to be fantastic. Built into Xcode or accessed online, the documentation includes sample code - and not just a snippet. It has full projects that you can load up and run. I almost never resort to stack overflow when I'm writing my iOS apps - the doc is simply that good, including hyperlinks to all data types and constants in the api methods.
You know that SO is crowd-modded as well right? Try posting some crap on there and watch it get modded down and deleted.
My big issue with nearly all modern documentation is the total lack of information on the architecture behind the API (or whatever interface I'm using). To write effectively you must be in harmony with the software environment you are working with, but 99% of the documentation explains (in brain bending detail) that when you press the 'y' key, you get a 'y', well yes I already had that sussed guys, what I really need to know has to be teased out by reading the documentation, endless posts on stack overflow and many other places. It's all very well explaining how to make my model rotate in opengl with some guys favorite series of calls, but I want to know WHY you do it that way, 'cos without this knowledge every minor change becomes a trip into the unknown.
"how to do it" Documentation is provided as a set of incantations where a very specific recipe gives a very specific effect, but if you change the eye of frog on line 42 for eye of toad - well the results are dramtically different (assuming you live to tell the tale). I want the same sort of information I was taught in school countless years ago in science lessons about electron orbits, valency etc. which brough the periodic table to life, and meant you could predict what Molybdenum would be like because of the number of protons.
I'm on my 3rd total rewrite of an android app, 'cos I've slowly been learning how to go with the android flow because of this lack of meta information. Some time you find a few gems - in the case of android, quite often this is videos from the android team at various big events.
This is exacly the same problem I had many years ago trying to write for Windows, the API information was like most microsoft help - totally helpless. Interfaces are explained in great detail, but with almost zero information contents. I need to know WHY I would choose to use the value, and what it's effect is (particularly when combined with other values provided to other related API calls.
I can think of only a few situations where I've come across information that actually made me feel I understood what was really going on from the start, for example in the XSLT Programmer's Reference by Michael Kay (5 out of 5 for that one). The OpenGL Superbible (several authors) was also pretty good (I'll give that 4/5 - good but still resorts to incantations in many places. Oh yes "PostGIS in action" Regina O.Obe and Leo S. Hsu is pretty good too but still in the thick of that one so not sure on the final score yet.
Looks like books can still hit the right spot - unfortunately just not the ones that are supposed to document the product in question.
Of course the real problem with many API's is that the various interface calls are full of side effects and the underlying code is riddled with 'optimisations' to try and improve performance, with the result that a slight change in the use and the whole thing falls apart. Android, Windows and the various linux gui platforms all fall into this bear trap, and I suspect that it's the lack of a properly documented architecure as a guiding light for everything that happens below which is the real cause of the poor documentation.
There are times that PHP (mod_php, more specifically) is the best tool for the job. But the argument is that it's a bad language -- poorly designed, inconsistent, etc etc.
Do you even lift?
These aren't the 'roids you're looking for.
I remember back in the .NET 1.1 days, googling most .NET things returned an MSDN link, and sometimes going directly to msdn gave even better results. Fast forward a few years to .NET 4.0 and MSDN is fragmented beyond belief and cross versions solutions don't always work. So you might find the solution in 4.0, try to apply it to 2.0 and find that there's no 2.0 version of the doc and the 4.0 doesn't work.
SO works more on the crowd principal, where more relevant posts are updated the most and happen to be timeframe relevant. Also, you can always ask a question yourself.
MSDN is set in stone, and the social site MS has and other dev networking sites, just don't have as much interesting stuff as SO, don't rank as high in the search, and have much slower response times. SO is good at what it does, MSDN has fragmented, I'd say that is the main reason SO is in the title of the article today.
My post is primarily about .NET, but there's everything on SO, including stuff like REST, php, all versions of SQL, etc...
Mashups?
You MUST be less than thirty years old. Christ, that's such an ugly term.
Assuming your interpretation of that code is correct, how about:
std::set<Foo> foos(vec.begin(), vec.end());
*Much* clearer than either example.
Better examples exist in other languages too I'm sure.
ps, the above code is from Stack Overflow.
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.
Since people are pissing on PHP, might as well add their version:
$output = array_unique($input);
sort($output);
"Our two-party system is like a bowl of shit looking at itself in a mirror." - Lewis Black
I had the unfortunate job of re-writing an Excel VBA app last year and I can say based on my experience that the Microsoft documentation for VBA (much like that for the rest of Office) range between useless and non-existent.
For the vast majority of my searches for "Excel VBA topic", a Microsoft site wouldn't even be on the first page, and perhaps not even the second.
Without forums like Stack Overflow, I would not have been able to finish the task... or it would have taken much longer. As it was, I still had to fall back to trial-and-error because VBA is, easily the buggiest, most fragile and most poorly documented development platform I've ever used in 25+ years.
You are in a maze of twisty little passages, all alike.
Most of what I see of the articles at Stack overflow are about syntax and symantics of how to problems in a specific language. Most of the company sponored documentation is organized differently, by feature and what its parameters are, not generally how to use it in conjunction with other language parts or even what the intent of the use is.
I see the same thing at work with a new task / hours data entry which is a spreadsheet with 100 rows of projects. I had to comment to my boss that this document was tuned for executive use not for data entry. Different needs need different views.
Also there is the sub-dialect problem. If you are comming from Java and having to do the same thing in c# they call the same thing by different terms, and the frameworks are maybe equivalent but stuctured differently, so the Stack overflow query on more common terms and problem specific language gets you a solution much quicker than trying to navagate the traditional document hierarcy. That is not to say you don't need both views, you do. But usually software only gets the one view. The other is built from the deficiencies and idiosincracies of the software.
You don't HAVE to do it that way. You chose to do it that way. Why should the language prevent you from doing what you want?
Nonsense!
:
.*\n # anything followed by a new line
/
# create a list containing
# the result of joining "undefined" with nothing
(
$l=join("",)
)
# in other words, a single-element list, the element being an empty string
( "" )
=~ # regex
s/ # substitute
# gibbersih we don't care about, because that ("") doesn't have a newline, so it won't match
No need to decipher more. Just fire whoever wrote this, and get a Real Perl Programmer.
... why stackoverflow is always in the first few hits google presents. Given that almost all the answers there are obviously totally wrong and the only answer not totally wrong is usually moderated down to the end, I always thought they were using some sophisticated search engine optimisation. But if people are actually reading the site, that might explain why google still presents it in the search result.
I'm really frightened considering how software developed from people using stackoverflow answers might look like, though.
Developers May Be Getting 90% of Their Documentation From Google, and 50% of the time the first result is from Stack Overflow and it contains the correct information.
...I thought it meant that developers were showing a preference for documentation generated as a result of an actual stack overflow. Stupid ambiguous capitalization...
..before I use them for real. That means I test many different inputs and contexts so I have decent knowledge of their behaviour before construction of the application.
This means that I know in time of its (unexpected) idiosyncracies and also possibilites that is not immediately recognized.
Mundus Vult Decipi
I hate stack overflow and always filter the site out when googling. It's a spam site where every single easy problem gets an overflow of overly complex, stupid solution suggestions from amateurs. It's truly a bad place to look for documentation. Bad practices all the way.
Just for the record, I find the linux manpages to be extremely helpful and well put together. And that's good, because I can never seem to remember the order of the damned arguments to memcpy(), even after 19+ years of unix programming.
- --
"I Hate Quotes" -- Samuel L. Clemens
I always check the docs first and try to figure things out myself before looking elsewhere.
Crowdsourcing is great and all but even stackoverflow the best of the best crowdsourced resources is full of people who treat it as a game and try and rack up as many points as possible and don't really always know what they are talking about. This is especially a problem in some thin areas where the global pool of knowledge is shallow.
The point of the "documentation" is to provide a kind-of library where one can search an interface to find an explanation of what it does (and sometimes how it works). The point of Stack Overflow is to provide answers to questions, which might nuance the interaction of various parts of an interface in specific contexts. So the comparison isn't really fair. They're both useful in different ways.
SO does have some good insight into Oracle and Microsoft (What I code in) problem/solutions. There are also some really good questions asked that don't get answered though.
If MS could just add some relevant examples to their documentation or have good answers on their forums, I would start with their sites.
Also, has anyone checked to see if Bing really is better for MS specific searches?
ss
I can't complain, but sometimes I still do. - JW
Enjoy!
https://www.cs.duke.edu/courses/cps196.1/current/classwork/Lethbridge-Singer-Forward-2003.pdf
I think one should consider that there are 3 distinctive source of help/information serving somewhat different but overlapping goals:
1) Comprehensive books on the subject - especially useful when learning new technology from scratch to get a general overview of the whole environment/functionality/language/tools and how all pieces work together to create real life application. They often contain fairly comprehensive API description overlapping with:
2) Official online documentation (MSDN and alike) - complete API/technology reference with some of how-tos
3) Crowd sources - MSDN forum, Stack Overflow and other forums. Mostly geared towards giving answers to specific real-world question that cannot be answered by 1) and 2). Extremely useful because nobody can predict all possible real life scenarios and this is where the strength of the crowd knowledge really shines through because more often then not - whatever you problem is there is a good chance someone already experienced it and possibly found solution.
Goals mentioned above include learning, applying what you learned to real-word problems and solving issues that one comes across along the way.
I was there four times today alone.
Although I use cplusplus.com or docs.python.org for specific API questions, for how or why questions, stackoverflow is the best.
I wonder what will become SO after it has been sold to Microsoft.
Slashdot, fix the reply notifications... You won't get away with it...
That way you know ahead of time what should be done.
You also get a better grasp of what the problem being solved.
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.
Bad documentation is not the only problem. I keep noticing LAZY developers and developers that could not write a "hello world" example without the aid of Experts Exchange.
PHP is a bad language. Any language that can return null from strcmp and have it be coerced to a 0 (the equal value return code) instead of throwing some kind of error is a bad language.
In my experience, the answers on Stack Overflow are examples of a particular usage, instead of documentation of the usage of a particular function or class. The MSDN documentation serves it's purpose when you specifically need to know how something works, but Stack Overflow functions much better when you need to know what to use to accomplish a specific task.
What would you expect Microsoft do? Preconceive every possible use of the .Net framework, and create examples for everything? Of course not, and this is why the crowd sourced approach works so well for this instead. It must be far more efficient to pool mental power when it is needed, and answer specific questions with example.
PHP is good for one thing - the trash can.
The cesspool just got a check and balance.
PHP is shit. I use it and make a living with it, but it's shit.
A tutorial walks you through how to do something. If you want to figure out how to do something, you go to a tutorial.
A reference describes the tools you use to do something. If you know have a very good idea of what you want to do, you go to a reference to get the detailed view of the tools you plan to use.
StackOverflow is an interactive tutorial. A lot of documentation is just a reference (and imperfect/incomplete ones at that).
Fact is that often when you search for info about a question on SO you find several entries that maddenly skirt around the question and provide no real answers other than parroting the common knowledge.
That explains why there is so much traffic there. Probably one out of four hits from a developer actually lead to useful info. That's more than enough to be useful which is why developers keep going to SO, but there is also an awful lot of useful info in the blogosphere that cannot be found on SO.
Let's just say that's a bit conservative
Freedesktop, ubuntu, microsoft, C++ and most likely many more, just have an incredibly shitty and incomplete documentation. Operating system components in general have bloody aweful documentation! Gnome and the free desktop project have me constantly shouting at the screen for despicable lack of documentation.
Java with their javadoc, python with whatever it is they use and ruby with their RDoc have made useable documentation and made tutorials available on their homepage. I barely have to use stackoverflow except when I run into something pretty out of the ordinary. And if you don't find the answer, you can look at their code, because that's commented as well. Obviously these guys are doing something right...
You think that the language choice is what makes or breaks performance at the internet mega-site level? I'm starting to get a suspicion that you might not know what you're talking about.
The only authoritative reference to how a system functions is the source code. If you don't have the source, at some point you will encounter the problem that is unsolvable without it. Unless of course the original programmer wrote about everything that could ever be done with his software.
With source code, all things are possible. Not necessarily pleasant or easy, but possible.
Those who advocate genocide deserve every protection afforded by law, and none afforded by common human decency.
Usually the official documentations are just horrible. It's a pain to read them and they lack of easy-to-understand examples and explanations. No wonder people rather use stackoverflow, at least there they get useable help and working code examples.
Actually, MicroShit has all but abandoned .net and win32 in a big time sacrifice to the tablet alter. This just further signals the demise of the crap called windows
Quit playing Monopoly with Bill.
Linux - of the people, by the people, and for the people.
PHP is not a good language, period.
It may be a reasonable choice for some cases, but solely because 1) you can find very cheap hosting for it, and 2) you can hire very cheap devs for it. There's literally nothing that it does better or faster than other languages in the same niche (dynamically typed - Python, Ruby, Perl etc), and it's objectively worse in many aspects (how's that Unicode support going?).
Any language can be used responsibly. But some force you to do it, others make it easy if you know how, yet others make it harder than creating a mess. PHP is firmly in the latter category. It encourages bad programmers to be bad, and punishes good programmers for trying to do the right thing.
The first question that comes to mind after seeing this is, why array_unique has the array_ prefix, but sort does not?
I mostly agree, though I think that PHP 5 no longer punishes you. PHP 4 definitely dissuaded you from doing things "right".
I still can't get over it's total lack of threading. To stay on-topic, I will say that the documentation web site is pretty darned good.
W..w..W - Willy Waterloo washes Warren Wiggins who is washing Waldo Woo.
Your code has a terrible, horrific bug. You're throwing away the array values.
Here is what you want:
my @outputarray = sort keys %{{ map {$_=>1} @inputarray }};
I still stick behind my original post though, and I will reiterate
>so if you can get from point a to point b, why trade in your old bike
I f it still does what you need it to and do not need to change it, then why change it for the sake of saying you changed it for newer technology...just another way to make you spend your money.
I understand your analogy and it does make sense, but that was not the comment i originally made, I said if it ISN'T broken...why change it for the sake of changing it? If the frame will hold for the next 100years, there is no reason to change it then
Not sure why should be considered a problem. StackOverflow offers reviewed, edited documentation from people who actually use/enjoy to technologies they're describing.
By providing documentation filtered through the real world, you get useful information that describes how features DO work, and not how they WOULD work if they were implemented the way some unknown documentation writer described them.
To me, the SO solution is MUCH better than written documentation, and I've quickly picked up a working knowledge of entire new platforms, languages, etc. just by getting the answers to questions I needed, rather then sifting through tomes of irrelevant information and "Hello World" examples. SO is good documentation; perhaps companies should have their doc writers participate in discussions there, rather than formatting new whitepapers and PDFs.
I would have thought someone would have asked why array_unique takes a parameter by value, and sort by reference.
Regardless, it's obvious what that code is doing. I would argue those 2 lines are even clearer than the other examples, even though they aren't consistent.
(the likely answer to your question though is that sort was part of the language before they added the array_ functions)
"Our two-party system is like a bowl of shit looking at itself in a mirror." - Lewis Black
.
If they lost control, someone else would become the leader and their income would be one-tenth as much.
So, to maintain control they increase complexity. The Word .doc file size used to be my metric. Used to be you could create a 1KB "hello world". Then it became 20K -- arounnd that time they were referring to the DOC as a file system in itself. Probably up to 100K now.
Another unstated goal is minimal documentation. Or, equivalently, voluminous documentation. Anything but exactly the right amount of documentation. This way you force people to dedicate their career to your products -- blink and you get behind, grovel at the trough of Microsoft and you keep your teat.
Another goal is to cover functionality in the most minimal way possible. Introduce a few new bugs/limitations if you want a Christmas bonus. Oh, and fix a couple of bugs from before. This could be called the Wonder bread approach. Fortified so that it keeps you alive, just barely. Anything to string people along like beggars getting their hand-outs.
Still, all that said, I prefer Windows to other operating systems. The devil I know best, I suppose. Biggest issue I have with Linux/Unix is gnarly syntax -- I love tiny one-purpose programs, piping, etc. -- but crap syntax produces write-once code, crap productivity, and undocumented systems.
I come here for the love
Perhaps it's not the documentation itself, but the way it's being delivered. Traditional tech pubs are often difficult to search and woefully outdated. We're trying to do something about that here at TerraXML.
Unicode support? Standard library still being an incoherent mess (well-documented one, though, I'll give you that).
Take an arbitrary list, and output a sorted liste with no duplicate entries
In that case, sh wins this readability pissing contest:
cat list | sort | uniq
Yeah, well I'm all done defending PHP now :) If I am scripting, I currently like Python. It has some warts, and the speed isn't always fantastic, but it's my favorite right now.
W..w..W - Willy Waterloo washes Warren Wiggins who is washing Waldo Woo.
@gameweld
Based on your post my 1st thought after briefly remembering the hell you have to ENDURE when a BSOD error hits you havent seen before or its been so long ago you forgot what the ultimate fix turned out to be-is this--> do YOU find MS documentation even readable let alone useful?!?!
its written based on my experience as a guy who just builds his own box and learns thru the school of hard knocks the MS doc is worse than useless-it only hints at this being the cause and offers if at all any fix(s) such vague techno/lawyer speak to be functionally useless. I taught myself BASIC on a trash-80 using Tandy manuals as my teaching aids as a kid, and can converse well enough with a COBOL programmer to fool them I'm one too. I also taught my self SPSS on my college's mainframe. SO I'm used to reading and applying less than ideal reference material into getting a computing device to function.
Big probs with MS doc to my view is its not cataloged/organized/indexed/searchable so you can find info on your specific problem. Part of it stems from MS making its products be all things to all users -you can make something do everything well for every conceivable use. Part of it is MS unwillingness to render actual aid-if if advises you wrong-in today's world someone is going to be suing you-just ask Wal-Mart the most litigated corp in the world. Also how MS labels or names the issue/prob isnt what anyone who isnt IT technician, ie a profession who fixes and troubleshoots computer systems for a living which makes the finding the one doc out of probably billions so difficult to locate. (no offense intended to those who are much more than a tech who fix/troubleshoot for a living as part of your job)
In MD defense unless they have access to your computers complete build and software installed plus drivers used many problems can come from many different sources and are pretty difficult to pinpoint.
Technical documentation is bad because very few software projects identify documentation as a task they need to accomplish, in their Project Plan. Marketing does very little in their PRD. Engineering does next-to-nothing in their FS. When it finally does occur to the Project Manager that customers will need something, the engineers on the team think that it's a piece of cake. They already have an Engineering Specification; surely customer documentation can be easily extracted from the Project Spec -- the technical team can just 'wing' it the last month of the project, and everything will be fine. ... so the project deadline approaches. The spec has become grossly incomplete and out of date. The Engineering team has no idea who the buyers will be. Engineers generally lack the writing skills they need, to prepare long, detailed documents. They haven't defined anything; outlined anything; identified questions that users would ask. The Marketing team (involved by this time) doesn't really know how to write, either -- but they think they do; and they also think that usual Marketing bluster will get them by.
So things go wrong. Engineering and Marketing get in a fight, which wastes time. Sensing doom, the first few Marketing people leave the project. As a compromise, the Project Manager forces the Lead Engineer to assign someone on his team to document the product. The Lead Engineer assigns the most junior Engineers on the team. They fail to produce anything usable, because the Lead Engineer has also placed documentation last on their list of project priorities.
By this time, the Project Manager realizes he/she has a serious problem. To calm everybody down, he/she hires a technical writer at the last minute. He treats the writer pretty much as a secretary: No technical briefing. Not integrated onto the team. The Engineering Lead has placed the doc files under Engineering version control, where every misplaced semicolon in a doc file unnecessarily breaks the nightly build.
The Project Manager still expects the documentation to be finished on the same minute of the same hour of the same day that the product is released as an alpha/beta/PR -- sometimes a few weeks early, so it can theoretically go through QA first.
Through all this, no one (except the writer) has thought to ask what the customers (including the technical customers) actually need to know.
It always ends badly for everybody -- because the Project Manager and his initial team ignored their documentation requirement because it didn't look like it would cost enough to require their management time.
While Microsoft deserves some criticism; other large companies are worse (and more cynical about it). ... just make a list of the largest companies in Silicon Valley. None of them have instituted business processes that have a prayer of producing the tech documentation anyone can easily use. When they finally produce usable docs for a product, it's on the third or fourth version, several YEARS after the original deadline.
Open Source projects generally handle Documentation worse than this.
Yup, my point exactly. I'd understand PHP advocacy if it was the only dynamically typed language, but when you have Python and Ruby that are just that much saner designed, and can do all the same things at least as well, and usually better, PHP just has no excuses going for it.
I guess the point of my point was not to out-and-out deny yours, but rather to suggest that it's rarely so black-and-white. My faster, lighter, sturdier bike response to your old bike that works fine was to hint at the possibility that with the new one, the point was not just bragging rights, but being able to get from point A to point B faster, in less of a sweat, and with less likelihood of requiring some sort of maintenance.
It's a matter of degrees. I absolutely agree that old things shouldn't be thrown out just because they're old, but with a 25-year-old piece of code, just like that bike, there are probably worthwhile reasons to consider changes, and if those changes are major enough, there are probably worthwhile reasons to consider changing the underlying technology.
Sometimes, inertia is a good enough reason not to change because the reasons to change are not compelling. Sometimes, inertia is a terrible reason not to change.
The CB App. What's your 20?
I was ordered to write bad documentation. I told them there is no need to print a page showing what was on the screen and writing instructions down as to w hat was supposed to be entered in the Name and Address fields. imo, if you don't already know, you probably aren't going to read what I wrote anyway. I wanted to write answers to normal questions and the bugs that had already been found by testers but that got the kibosh.
MSDN is awful compared to what? I'm a .Net developer and IMO .Net is one of the most vast and well documented APIs created. A stack overflow entry supplies a very specific answer to a very specific question, so of course I can get a great answer to a very specific problem very quickly. The API documentation on MSDN is a tool you apply to answer your questions and understand the API and architecture.
I use MSDN a lot, I use stackoverflow constantly. To suggest their documentation was a waste of time is ludicrous. Where do you think the stackoverflow experts obtained the knowledge to apply it to the problem in question? Case and point, stackoverflow entries constantly refer to the MSDN and KB entries.
First and foremost, MS search products do not work. I am convinced they could not find their own brown holes if monkey boy's nose was stuck in them as a overstuffed flag indicator. If you are lucky to have a relevant hit using said search, the url is probably broken. On that rare 0.1% you actually find a relevant url, the data is either too concise or 40 pages long. Do that for 10 times a day when you are already time crunched and your mind is numb from over work and you begin to curse MS with extreme noxious venom. I used to use the built in context menus until MS dumped its entire encyclopedia of world knowledge into the product: topped only by the inclusion of another useless MS search product to search through the docs with.
When seeking .net help, few tools beat Google. Even if stackoverflow was not the on top of the Google results, I would hunt several pages for their urls to include in my research. Stackoverflow via Google contains some of the most relevant hits for quickly getting past your ms visual studio quirks and ms tech idiocy.
PS: VisualStudio97 docs were the best and vs6 were the last useful docs MS put out. Once they got rid of the old KB web site in the mid/late 90s, their website went to and remains in a useless state. In the old days, you could quickly find extremely helpful info, searching from one page (which was always there). Since that time, seems a psycho url switching policy took its place returning little more than broken links and useless dribble from "intellectual tech" posers.
Sorry, but .NET is alive and powers the new tablet apps.
This "Malbolge" sounds interestingly difficult to use. But what about Intercal?
Birds are not dinosaur descendants;birds are dinosaurs, for all useful meanings of "birds", "are" and "dinosaurs"
I've discovered LOLCODE, which is mad, but in a sane sort of way.
And then I've discovered "esoteric" programming languages. Actually, I've known of them for some time. "Whitespace", for example, is a language which I met several years ago from a different direction (it's the ultimate in steganographic programming ; the hard copy printouts consist only of ... errrr ... white space).
But I see a trend towards programming languages which have very small numbers of commands and operators. And this is where I think that I really should check what goes into the coffee machine, because it's getting weird.
I conceive ... (of) ... a programming language with a small vocabulary (commands, operators), which, with a "modified" keyboard, could produce valid code by a cat could walking across the keyboard. "I have a dream, LOLCATz and LOLKITTEHz ..."
Better (?), but probably harder to achieve, would be a programming language where correct code could only be written by a cat walking across the keyboard.
I'm not sure which is scarier - that I can think of such things ; that other people might just possibly agree with me that it's a worthwhile project ; or the terrible, terrible implications of Rule 34.
Birds are not dinosaur descendants;birds are dinosaurs, for all useful meanings of "birds", "are" and "dinosaurs"
From other sources, directly and mostly indirectly. Most experts answering questions sooner or later had to go in depth and "resort" to full and complete vendor documentation. Using this, they are able to post on stackoverflow.
Without the documentation source, noone would ever be able to obtain the knowledge in the first place. Except for some simple and self documenting systems/API's.
Surely it is not to be hoped that software providers are going to rely on "user generated content" and neglect reference documentation.
(No, I'm not a technical writer myself).
>there are probably worthwhile reasons to consider changes
I agree with you here, but the fact is that most companies do not want to invest money on recoding stuff that still works....which is why you can still walk into some companies running old dos systems
which is why you can still walk into some companies running old dos systems
DOS? My father used to build and deploy small nuclear reactors (cyclotrons) for use in medical/research facilities (specifically for creating radioactive tracers required for PET/CAT scans), and now acts as an independent consultant for the clients who've gotten those machines over the last 40 years or so.
He told me a few years back about going into a client facility with one of the older models, which had originally been run using a control system written on a PDP-11. At some point, the PDP-11 crapped out, and what the client did was get a beige box PC with appropriate ports added on in a slot, and with a PDP-11 emulator built in. They then hollowed out the rack cabinet where the PDP-11 had been housed and put the PC in it, along with some other equipment. With the cabinet door closed, it looked like it did the day it shipped.
I'd be a little worried about running a PDP-11 emulator on top of Windows 3.1 (IIRC, that was what the set-up was) for controlling a small nuclear device, but I guess it worked for them.
The CB App. What's your 20?