Slashdot is powered by your submissions, so send in your scoop


Forgot your password?

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

New submitter gameweld writes "Software companies, such as Microsoft, create documentation for millions of topics concerning its APIs, services, and software platforms. Creating this documentation comes at a considerable cost and effort. And after all this effort, much documentation is rarely consulted (citation) and lacking enough examples (citation). A new study suggests that developers are increasingly consulting Stack Overflow and crowd-sourced sites over official documentation, using it as much as 50% of time. How should official documentation be better redesigned? What are the implications of software created from unruly mashups?"
This discussion has been archived. No new comments can be posted.

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

Comments Filter:
    • Re: (Score:3, Insightful)

      It would probably help if more companies paid for the technical writers to do it themselves. Unfortunately, if they're anything like the last shop I worked at, the documentation was one of the first things that got shortchanged when times were tight.
    • by icebike ( 68054 ) on Tuesday March 05, 2013 @03:43PM (#43082335)

      Lots of truth to this.

      What you get from MSDN must be read like a lawyer parsing the law books.
      Miss some casual reference and the whole API call fails. Or worse, it almost always works, but
      fails inexplicably on odd numbered Tuesdays.

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

      That said Microsoft documentation is still more extensive than most. I often start there then end up on Stackoverflow
      of one of the other sites for more lucid examples, and often find that problems with a particular feature not working
      as documented are common knowledge, except, apparently, to Microsoft.

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

          In all seriousness, when I have a choice between two links, and one is the documentation and the other is SO. I choose SO first. Then check the documentation for the nitty gritty details.

      • by Z00L00K ( 682162 ) on Tuesday March 05, 2013 @04:30PM (#43083057) Homepage

        Microsoft and others writes a kiloton specific for the function it concerns, but nothing about the context in which it shall be used. Here's what StackOverflow is a lot better at - a lot of examples, some good, some not so good and some esoteric.

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

      • Too much vendor documentation is geared to lawyers, CYA and is needlessly verbose.

        Many web sites tell you what it really took to get something going versus how it's supposed to work.

        I read a lot of bad documentation. Remember English class where you took a few 3x5 note cards and padded it out to a five page paper? I've read too much vendor documentation that looks just like this. No economy of words.

      • by WuphonsReach ( 684551 ) on Tuesday March 05, 2013 @07:42PM (#43085807)
        Things also go missing. You will find something this week, only to find it missing with the next update to the website.

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

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

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

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

        They're not the only sinners in that regard, way too many other companies around the web constantly shuffle their documentation URLs around, breaking all the old links.
    • by Joce640k ( 829181 ) on Tuesday March 05, 2013 @03:58PM (#43082581) Homepage

      Yep. Microsoft documentation is truly awful.

      Typical Microsoft documentation page:

      DWORD throbTheWangle(DWORD Wangle, FLOAT HowMuch)

      This function throbs wangles.

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

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

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

      • Re: (Score:3, Insightful)

        by Anonymous Coward

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

      • by JDG1980 ( 2438906 ) on Tuesday March 05, 2013 @04:05PM (#43082663)

        One of the most annoying things about the MS API documentation is all the unexplained dependencies. You see a function call that takes 2 structure pointers as parameters and returns another structure... now you've got to open 3 additional documentation pages to read what those structs mean. And they might contain other structures of their own, so soon you can be up to half a dozen or more tabs, all for one API call you want to perform.

      • by jafac ( 1449 )

        you sir, have perfectly described it. So well, in fact, that my wangle is, indeed, throbbing.

        But seriously - this is probably the biggest challenge I face in my work - which I've been doing since about 1980. When I encounter some documentation, and there's no fucking context, and no reference TO context - that documentation just utterly fails. Here it is. 2013. And we still haven't solved the problem.

        I go to Stack Overflow, and read through a few extra pages of chitchat . . . and THERE is my context. Usuall

  • Blame Google (Score:5, Insightful)

    by Anonymous Coward on Tuesday March 05, 2013 @03:21PM (#43081959)

    Whenever I have a problem, I google it, and StackOverflow is always in the top of the results. If Microsoft want me to use their documentation they better make sure google indexes it in a way than matches my queries.

    • Re:Blame Google (Score:4, Insightful)

      by gl4ss ( 559668 ) on Tuesday March 05, 2013 @03:31PM (#43082145) Homepage Journal

      Whenever I have a problem, I google it, and StackOverflow is always in the top of the results. If Microsoft want me to use their documentation they better make sure google indexes it in a way than matches my queries.

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

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

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

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

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

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

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

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

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

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

      About the only time I go and look at the documentation directly is/was in Python, PHP, and LibSDL, who managed to have good organization to their stuff, compared to a lot of other groups. Though for examples i

    • by cruff ( 171569 )

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

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

    • Re:Blame Google (Score:4, Interesting)

      by MightyYar ( 622222 ) on Tuesday March 05, 2013 @04:49PM (#43083383)

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

  • by Hentes ( 2461350 ) on Tuesday March 05, 2013 @03:21PM (#43081963)

    Documentation and asking others for help when you get stuck complement each other. You can't really learn to use something completely new on Stackoverflow, and you can't predict all the ways people will screw up or misunderstand you in a documentation.

    • You can'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.

      • by Sarten-X ( 1102295 ) on Tuesday March 05, 2013 @03:57PM (#43082559) Homepage

        When all else fails, read the directions.

        Documentation should be the absolute authority on every detail of a system's operation. It should be the reference material for experts. On the other hand, people who aren't experts don't know the available options, and often don't really know the terms to look for in the detailed documentation, and can't spare the time or effort to read (and grok) the whole documentation end-to-end. StackOverflow is a great place to describe the problem you have, and experts (who know the system more fully) can point you in the right direction or even provide a solution. Then you can read the relevant documentation to understand better what's going on, and hopefully provide similar help to others.

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

          • Well no... but like I said, it should be.

            Police should also be unbiased, governments should be fair, and there should be peace and happiness and abundance throughout the world.

        • by SuperKendall ( 25149 ) on Tuesday March 05, 2013 @05:01PM (#43083611)

          Documentation should be the absolute authority on every detail of a system's operation.

          The Documentation has a huge problem. It lays out how the thing in question was MEANT to work.

          What StackOverflow offers is understanding of how it ACTUALLY works (or doesn't).

          Furthermore Documentation is written almost always with either very generic examples or examples imagined by the documentors or framework builders. StackOverflow offers examples from people who are trying to build something real that works.

  • Microsoft docs (Score:5, Insightful)

    by phantomfive ( 622387 ) on Tuesday March 05, 2013 @03:23PM (#43081985) Journal
    I don't want to pay $36 to read the study, so I can't comment directly on it, but

    | Microsoft's MSDN website changes frequently, and is confusing to use (on some iterations of their website, on others it works better). Currently to find anything, you have to use the Bing search on their web page, and it doesn't always work well. I find myself using Google search to search for functions in MSDN, because I get better results.

    As a result, if something for Stackoverflow comes up in the search results ahead of the MSDN docs, I'll probably look at that one. From that, I hypothesize that if people are looking at Stackoverflow, it's because they've done their SEO better (and probably have more motivation to do SEO).
    • Re:Microsoft docs (Score:4, Interesting)

      by dkf ( 304284 ) <> on Tuesday March 05, 2013 @03:40PM (#43082293) Homepage

      Microsoft's MSDN website changes frequently, and is confusing to use (on some iterations of their website, on others it works better). Currently to find anything, you have to use the Bing search on their web page, and it doesn't always work well. I find myself using Google search to search for functions in MSDN, because I get better results.

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

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

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

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

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

      I commonly will have questions on Stackoverflow asking for help understanding what the hell MSDN is trying to say. For inst

    • All very true.

      And of course, in some cases MSDN has zero documentation for stuff. For example, there's many instances of the Windows Scripting Host functionality where it is only documented in VBScript despite the fact that Microsoft fully supports JavaScript with WSH as well. So you have to turn to other sources to figure out how to do it in JavaScript if that's what you are using. (Yeah, it drove me nuts a few years back.)

      So now I use the MSDN search in Firefox, or use the "" featu
  • by Megahard ( 1053072 ) on Tuesday March 05, 2013 @03:23PM (#43081999)

    The problem is lack of usage examples and feedback. When you follow the API and your program doesn't work, the solution is to google your problem to find the solution from the 1000 others who have hit the same problem.

    • by phantomfive ( 622387 ) on Tuesday March 05, 2013 @03:42PM (#43082319) Journal

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

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

    • I'd go even further, and say that most of even the best documentation doesn't provide use cases and best practices. Picking on MSDN as an example, there are some really good articles out there about various topics, but there aren't a lot of articles on addressing a specific question or need. If you need to know how to use, for example, a treeview control, MSDN is probably the best place to go. But it doesn't answer the question, should I be using a treeview control to begin with, or are there other solut

    • by kompiluj ( 677438 ) on Tuesday March 05, 2013 @04:01PM (#43082611)
      In PHP docs with every item there comes the section for for "user contributed notes" which are sometimes pretty insightful (like there php strings intro [] 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).
      • MSDN also has user-contributed notes for most doc pages (e.g. open this [] and scroll to the bottom). They do get used occasionally, but not all that often.

    • by mortonda ( 5175 )

      The problem is lack of usage examples and feedback. When you follow the API and your program doesn't work, the solution is to google your problem to find...

      ... your own post from 5 years ago asking exactly the same, unanswered, question. *sigh*

    • by n7ytd ( 230708 )

      The problem is lack of usage examples and feedback. When you follow the API and your program doesn't work, the solution is to google your problem to find the solution from the 1000 others who have hit the same problem.

      If only there was a clear-cut way to tell Google, "Please hide all of the results that are on a forum with only one post in the thread". My 2nd biggest pet peeve about Googling for answers this way is the huge amount of search results asking the same question I have, with no answers.

      My #1 peeve is people taking a crack at answering the question with no understanding themselves about the problem. Answers like "I've never done this myself, but I think blah blah blah" or "Why would you want to do that? Boost

  • by us7892 ( 655683 ) on Tuesday March 05, 2013 @03:23PM (#43082001) Homepage
    Useless busy-work after-the-fact documentation is overrated and plentiful.

    Useful documentation is rare.
  • Vetted Examples (Score:4, Insightful)

    by imnes ( 605429 ) on Tuesday March 05, 2013 @03:24PM (#43082019)
    With documentation you usually just get an API reference, and maybe a simple example. With community sites like Stack Overflow you get vetted examples and best practices from real world users. It's almost always more helpful than just a static reference.
  • I know most of the answers I give out on StackOverflow are really just paraphrased MSDN documentation. StackOverflow just acts like a new aggregator in that sense I guess. It's not the source of information, but a place where information from other places comes together.

  • Unruly mashups? (Score:4, Insightful)

    by six025 ( 714064 ) on Tuesday March 05, 2013 @03:25PM (#43082055)

    For some development problems it is far quicker to search sites like Stackoverflow for a question / answer / example relevant to your specific case than it is to read the official (often poor) documentation and figure out exactly how it is "supposed" to work.

    Basically, someone else did the work - possibly found some "gotchas" - and shared the fruits of their labour. Remind me how is that a bad thing? Isn't this exactly what the World Wide Web was designed for? :-/


  • Unruly mashups? (Score:4, Insightful)

    by oji-sama ( 1151023 ) on Tuesday March 05, 2013 @03:28PM (#43082087)

    The nice thing about Stack Overflow (and such) is that someone, somewhere, has (usually) encountered the same problem I am currently working on. The official documentation I check when I want some basic examples on how to use something and what the different methods are supposed to do.

    I may have created a few mashups from examples, but most of them weren't all that unruly. Perhaps the implication is that the wheel isn't invented all that often?

  • by HaeMaker ( 221642 ) on Tuesday March 05, 2013 @03:28PM (#43082099) Homepage

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

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

      Python docs are much more readable (the module documentation at least; the language reference is too technical and not needed for normal programming task

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

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

  • 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.
  • by Todd Knarr ( 15451 ) on Tuesday March 05, 2013 @03:35PM (#43082197) Homepage

    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.

  • 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?
  • by Bill Dimm ( 463823 ) on Tuesday March 05, 2013 @03:49PM (#43082443) Homepage

    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.

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

  • 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
  • by tlhIngan ( 30335 ) <> on Tuesday March 05, 2013 @03:53PM (#43082499)

    A lot of Stack overflow questions I see are along the form of "I need to do X, how do i do it?".

    Basically they want a HOWTO of which APIs to string together in order to accomplish their task, if not someone else to completely code it for them. This is often referred to as "task based" documentaiton - to do X, you do A, B, C, and D. This often fails if you need more details on individual API calls.

    Official documentation like MSDN exist to document all the APIs, but often lack what's known as "task-based" documentation.

    They're both required pieces - task based is often used to learn how to do things (e.g., how to create a window on Windows), while the API documentation serves to comprehensively adjust various settings (do you want a scroll bar? A resize box? etc). Unfortunately, putting in extensive examples inside such documentation often serves to confuse (you won't believe how many people assume you can copy and paste it into a program and have it run).

    Unfortunately, Stack overflow also suffers from developers merely copying and pasting code and expecting others to do their work for them (see thedailywtf), as well as many "give me the codez" stuff posted by students wanting others to do their homework.

    But when used properly, the two complement each other. Its like man pages versus HOWTOs on Linux - one documents the commands and APIs, while the other tells you how to properly string them together to accomplish things.

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

  • by Overzeetop ( 214511 ) on Tuesday March 05, 2013 @04:00PM (#43082605) Journal

    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.

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

    A couple of years ago I needed greyscale images, nothing fancy but using color was just silly, and wasted over a day try

  • 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.
  • 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... (Score:4, Funny)

    by Ghostworks ( 991012 ) on Tuesday March 05, 2013 @04:05PM (#43082669)

    How should official documentation be better redesigned?

    It should exist.

  • In my experience, official documentation tends to fall in two categories:

    Category A, the features manual. You can do this, you can do that. You can manage things like this and this. You can setup this to do that automatically. But no word on how to accomplish any of these things, or even what specific named feature to use.

    Category B, the reference manual. This feature has these options. This other feature has these other options. This third feature has these options. Each entry is usually accompanie

  • 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.
  • The main reason why StackOverflow keeps coming up for me over and over again is because when I Google for my exception or error code, I get real anecdotal evidence of other people seeing the same exception and then other people helping resolve those exceptions. Microsoft's technet is pretty decent at searching for exceptions/error codes, but typically only show up for older products (i.e. newer products are too recent and not as adopted so less errors are discovered by the community at large) and many time

I've never been canoeing before, but I imagine there must be just a few simple heuristics you have to remember... Yes, don't fall out, and don't hit rocks.