Slashdot Mirror

← Back to Stories (view on slashdot.org)

Bugs In Microsoft Technical Documentation Rising

Posted by kdawson on from the costs-of-monopoly dept.

snydeq writes "The number of bugs in technical documentation for Microsoft communication protocols continues to grow, according to court documents filed for ongoing antitrust oversight of the company in the US. Problems with the technical documentation — which includes 1,660 identified bugs as of Dec. 31, up from 1,196 bugs on Nov. 30 — remain the major complaint from lawyers representing the group of 19 states that joined the US Department of Justice's antitrust lawsuit against Microsoft. Lawyers for the states have complained repeatedly that technical documentation issues are opening faster than Microsoft can close them. Nearly 800 Microsoft employees are working on the more than 20,000 pages of technical documentation, according to the court documents filed Wednesday."

25 of 146 comments (clear)

  1. I didn't know you could get sued for bugs. by kbrasee · · Score: 4, Insightful

    I better write some more unit tests...

    1. Re:I didn't know you could get sued for bugs. by kbrasee · · Score: 4, Insightful

      Don't play the stupid card, it's pathetic.

      They're not sued for bugs but for abusing their monopoly...

      whoosh

  2. Re:To the editors by bogaboga · · Score: 4, Informative

    For a browser, use Firefox with a properly installed ad-blocker extension. Heck, there are remedies to this. So stop whining.

    Now back to the topic. I think this could be a delaying tactic by Microsoft.

  3. Shocked, shocked that there is gambing going on... by cwAllenPoole · · Score: 4, Interesting

    ... ... ... ...

    I think that MS needs to realize that one of the major reasons that standards exist is to PREVENT these things from happening. If there weren't so many inconsistencies, this would be markedly more difficult.

    But what do I know about MS anyway? Who am I to comment on their ineptitudes? I use Linux.

    --
    http://www.allen-poole.com/
  4. "Bugs"? by Anonymous Coward · · Score: 5, Insightful

    Do they mean documentation shows bugs with Microsoft's communication protocols or that the documentation is incomplete or erroneous?

    1. Re:"Bugs"? by DigitAl56K · · Score: 4, Informative

      What bothers me most about MSDN documentation is that I've noticed information pertaining to the behavior of common API's on older versions of Windows disappearing. Just because Microsoft no longer supports an OS doesn't mean that a developer does not want to write compatible code for it. Sometimes I have to refer to local copies of older MSDN documentation and the online version to get a complete picture.

      I also dislike that often searching MSDN documentation for C API's often results in you getting the .net versions as the top results, a cunning way to push their own languages I'm sure but I find it very annoying.

  5. When you have documentation by El+Lobo · · Score: 5, Insightful

    When you have REAL documentation, and millions and millions of technical pages about APIs, applications, several operative systems, you will have some millions of documentations bugs as well. Hell, even in some(very poor documented, as many are as a norm) open source projects there is a lot of wrong or not up to date information. Just look at, for example, the Indy open source documentation with several hundred of empty pages with a "to be complete" caption since year 2001, and even there I found some wrong interface description exactly yestarday. So how can I call this "article" news? Oh, the old habit of bring to front something "negative" about you know who, I get it...

    --
    It's time to realise that Abble's products are the biggest abomination these days. Just say NO to the dumb iAbble way!!
    1. Re:When you have documentation by Yvanhoe · · Score: 5, Insightful

      It puts emphasis on a common problem with closed-source : if you have a very buggy documentation you can't use the old trick of hand waving and say "read the source, Luke"

      --
      The Wise adapts himself to the world. The Fool adapts the world to himself. Therefore, all progress depends on the Fool.
    2. Re:When you have documentation by Opportunist · · Score: 4, Funny

      *waves hand*

      This is not the documentation you're looking for.

      --
      We used to have a Bill of Rights. Now, with the rights gone, all we have left is the bill.
    3. Re:When you have documentation by El+Lobo · · Score: 3, Insightful

      It puts emphasis on a common problem with open-source: you can have a poor or inexistent documentation and just tell the first fucker: "read the source, Luke" even if it is written in Fortran 94 with no commentaries.

      --
      It's time to realise that Abble's products are the biggest abomination these days. Just say NO to the dumb iAbble way!!
    4. Re:When you have documentation by truthsearch · · Score: 3, Insightful

      In general, you are correct. But we're only talking about 20,000 pages. And there are 800 people on the task. And this is a legal requirement. I think there should be very very few mistakes in this documentation.

      --
      Developers: We can use your help.
    5. Re:When you have documentation by fermion · · Score: 4, Insightful
      This is not true. It is possible to create documentation that is very complete. In the almost 30 years of writing code, I have found MS to be the worst. Worse, in terms of technical accuracy, than O'Reilly. The later provides better explanations, but the errors in both are annoying.

      In the DOS days, MS documentation was unusable. To do anything, one had to have a secondary unauthorized source. In the same timeframe, I also used DEC VMS Fortran and the IMSL library. I found the documentation of both of these very good. I never found a case where the DEC and official IMSL documentation did not match the behavior. Though the VMS Fotran documentation was just a sample, the VAX VMS documentation sat on a talbe 8 feet long. In a more modern case, I have used many libraries, such as the Boost C++ libraries, that put the MS documentation to shame.

      In terms of OSS, external human readable documentation become much less of an issue. The source code is there. if something does not behave as expected, one can look at the code and figure out why. If one is really nice, since most OSS documentation is collaborative, one could even change the documentation to match the true behavior or add a not about unexpected behavior under certain conditions. If MS provided free and unfettered access to source code, so that at minimum any person who bought a copy of MS Visual Studio received a copy of the source code without having to sign any non disclosure agreements or the like, then I would agree. These complaints would be meaningless. After all, if you can't read code and figure out what is going on, then why are you programming in the first place?

      But MS does not provide access to code to the common programmer. Nor does it have a history of provided reliable documentation to the common programmer. It does have a history of limiting what non-partner companies can do. So, all that is being asked is that it reliably documents it's API. To believe that it can't is to believe that we are basing our IT infrastructure on products from an incompetent company, so we choose to believe that it won't.

      --
      "She's a scientist and a lesbian. She's not going to let it slide." Orphan Black
    6. Re:When you have documentation by DerekLyons · · Score: 3, Insightful

      When you have REAL documentation, and millions and millions of technical pages about APIs, applications, several operative systems, you will have some millions of documentations bugs as well.

      Indeed. The system I worked on in the Navy had over a hundred volumes of documentation, which has been looked at by thousands of qualified eyes (between the contractors, DoD/Navy civilian employees, and sailors) over a period of a decade. Despite formal and informal reviews, an ongoing updating effort, and the documentation being closely studied and in daily use... Still we found bugs.
       
      Virtually all of them were minor typographical errors, but still they were there.
       
      Bug free documentation, I suspect, is like bug free programs - something attainable in theory but not in practice.

  6. Not MS's fault. by R2.0 · · Score: 5, Funny

    The order said that MS had to provide documentation. It didn't specify that it had to be correct.

    --
    "As God is my witness, I thought turkeys could fly." A. Carlson
  7. It was the best of times... by Anonymous Coward · · Score: 5, Funny

    ...it was the worst ofIRQL_NOT_LESS_OR_EQUAL

    Technical information:

    *** STOP: 0x000000D1 (ox20000001, 0x00000002, 0x00000001, 0xF6EA8BBF)

    *** OLEAPI.PDF - Address F6EA8BBF base at F6E8F000, DateStamp 3f04cf17

  8. Re:To the editors by jonaskoelker · · Score: 5, Funny

    Please stop posting articles from info world. The have ads after every page of the article

    O_o How do you know this???

  9. Questions by BoneFlower · · Score: 4, Insightful

    Are these old documents they've just now gotten around to reviewing, or are these bugs largely in new material?

    If the latter, how does the bug per page ratio stack up with the past?

    Depending on the answers to these questions, the quality of the documentation may actually be improving. It may be going down as the summary and article seem to imply, but we can't really say either with any confidence given the information provided.

  10. Re:Wonderful by pjt33 · · Score: 3, Informative

    I once copy-pasted some demo code from MSDN and it didn't work. That's a bug in documentation even by your standards.

  11. Re:Shocked, shocked that there is gambing going on by Opportunist · · Score: 5, Insightful

    Because documentation bugs, if any MS bugs, directly affect Linux users. Faulty documentation leads to faulty implementation of MS formats, I leave the rest to you.

    --
    We used to have a Bill of Rights. Now, with the rights gone, all we have left is the bill.
  12. Re:To the editors by DFJA · · Score: 4, Funny

    You're not supposed to RTFA, idiot!

    --
    43 - For those who require slightly more than the answer to life, the universe and everything.
  13. Re:To the editors by truthsearch · · Score: 5, Insightful

    The best remedy is to stop going to sites that don't mind annoying their users. Why reward them with traffic so they can go sell more ad space? We wouldn't need ad blockers if we only visited sites that are interested in keeping their readers happy. If they have no interest in giving me a positive experience then I have no interest in going there.

    Now back to the topic: I don't think this is a delay tactic. I think it's incompetence stemming from a lack of interest in providing good documentation.

    --
    Developers: We can use your help.
  14. They could start.. by OneSmartFellow · · Score: 3, Interesting

    .. with simply completing the TDS specification. Prossibly one of their most widely used protocols and it's entirely out of date, and what's there is incorrect in many ways or just incomplete.

    They should prioritize, but I'll do it for them.

    1.)SMB
    2.)TDS
    3.)whatever the hell goes on with Exchange
    4.)remote desktop
    5.)MSN
    6.)the rest

  15. Why don't they release the docs *they* use? by Prototerm · · Score: 3, Funny

    They're in text files with a ".h" or a ".c" extension, right?

    Oh, wait.

    --
    "My country, right or wrong; if right, to be kept right; and if wrong, to be set right." --Senator Carl Schurz (1872)
  16. Re:I'm sympathetic by Amazing+Quantum+Man · · Score: 3, Insightful

    And therein lies the problem. MS should have created a spec for their networking protocols BEFORE implementing them.

    --
    Fascism starts when the efficiency of the government becomes more important than the rights of the people.
  17. Re:I'm sympathetic by Amazing+Quantum+Man · · Score: 3, Interesting

    Because it causes problems for THEM, regardless of the EU.

    This may be apocryphal, but ISTR reading somewhere that when they needed documentation (for internal purposes) on SMB, they had to use the Samba guys' stuff.

    --
    Fascism starts when the efficiency of the government becomes more important than the rights of the people.