Catch up on stories from the past week (and beyond) at the Slashdot story archive

 


Forgot your password?
Close
typodupeerror
×
Bug Government Microsoft The Courts News

Bugs In Microsoft Technical Documentation Rising 146

Posted by kdawson 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."
This discussion has been archived. No new comments can be posted.

Bugs In Microsoft Technical Documentation Rising More

Bugs In Microsoft Technical Documentation Rising

Comments Filter:

  • I didn't know you could get sued for bugs. (Score:4, Insightful)

    by kbrasee ( 1379057 ) on Friday January 23, 2009 @11:23AM (#26574761)
    I better write some more unit tests...

  • Shocked, shocked that there is gambing going on... (Score:4, Interesting)

    by cwAllenPoole ( 1228672 ) on Friday January 23, 2009 @11:24AM (#26574783) Homepage

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

    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.

  • "Bugs"? (Score:5, Insightful)

    by Anonymous Coward on Friday January 23, 2009 @11:25AM (#26574791)

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

    • Re: (Score:1, Interesting)

      by cosam ( 460350 )
      They were obviously instructed to produce documentation that accurately reflects their software. So that would be latter...

      • Re: (Score:2, Insightful)

        by morgan_greywolf ( 835522 )

        And there's the difference between 'open standards' and 'Microsoft being forced to open their standards': The open standards folks produce software that accurately reflects their documentation.

        • I've read through a lot of open software documentation, as well as some non-open documentation.

          The only real difference seems to be the readability of open documentation; it's easy to read, but I wouldn't say I've found any form of doucmentation to be particularly reliable.

    • Re: (Score:3, Informative)

      by jonaskoelker ( 922170 )

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

      I'd think "bugs in documentation" means the documentation is doing it wrong. Doing it right would be accurately and fully describing what it's supposed to document.

      So I figure it means incomplete and/or erroneous.

      I'm of the viewpoint that a disagreement between observable software behavior and claims stated in the documentation is a bug in the documentation: it's either incorrect, or it's incomplete in that it doesn't say "beware of the software bug [...]".

    • Re: (Score:2, Informative)

      by ryry ( 198300 )

      I read it as that the documentation is incomplete or erroneous. The article talks about "technical documentation issues" and says "the company is working to fix problems with the documentation".

    • Re:"Bugs"? (Score:5, Informative)

      by DigitAl56K ( 805623 ) * on Friday January 23, 2009 @03:31PM (#26579167)

      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.

      • Re: (Score:2)

        by jrumney ( 197329 )
        This is particularly annoying. MS documentation used to be very good in this aspect, now if it says "Included on Windows 2000 and later", you don't know whether it really means that, or it was introduced in NT 3.1 and Windows 95. Also there are cases where they've blanked out pages for no apprent reason other than to prevent third party developers from using their APIs effectively - see the documentation for the Unicode Subrange Bitfield of FONTSIGNATURE, which was fully documented a year or so ago - at lea

  • When you have documentation (Score:5, Insightful)

    by El Lobo ( 994537 ) on Friday January 23, 2009 @11:30AM (#26574865)
    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...

    • Re: (Score:3)

      by El Lobo ( 994537 )
      Oh NOWWWWWW i get it. The editor was the dear KDAWSON. Now everything is clear.

    • Re:When you have documentation (Score:5, Insightful)

      by Yvanhoe ( 564877 ) on Friday January 23, 2009 @11:47AM (#26575059) Journal
      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"

      • Re:When you have documentation (Score:5, Funny)

        by Opportunist ( 166417 ) on Friday January 23, 2009 @11:55AM (#26575147)

        *waves hand*

        This is not the documentation you're looking for.

      • Re:When you have documentation (Score:4, Insightful)

        by El Lobo ( 994537 ) on Friday January 23, 2009 @11:56AM (#26575173)
        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.

        • Re: (Score:3, Insightful)

          by D Ninja ( 825055 )

          You were modded Flamebait (and it may have to do with how you phrased your argument - leave out the swear word next time), but you make a good point.

          One thing I *dislike* about many open source products (and I use a lot of them - I love open source in general) is that documentation can be very difficult to come by. And, there have been times I have gone into forums/IRC/etc for help only to hear, "Why don't you just read the source code?" I'm sorry - that's just not really an option for so many reasons I d

    • Re:When you have documentation (Score:4, Insightful)

      by truthsearch ( 249536 ) on Friday January 23, 2009 @12:20PM (#26575545) Homepage Journal

      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.

      • In general, you are correct.

        And in specific, GP is also correct.

        But we're only talking about 20,000 pages. And there are 800 people on the task.

        1. Most of those 800 people are probably technical writers, and not the engineers who wrote the code initially.
        2. 20000 pages / 800 people = 25 pages per person. Doesn't sound like much, does it? Until you consider that...
        3. Everything on 1 person's 25 pages must:
          1. match up correctly with the other 19,975 pages the other 799 people are responsible for
          2. match up correctly

        • match up correctly with the other 19,975 pages the other 799 people are responsible for

          I thought that's what templates were for...

          • And how exactly do templates do anything to solve the problem of making sure that your documents are internally consistent, and consistent with the behavior of the application?

    • Re:When you have documentation (Score:5, Insightful)

      by fermion ( 181285 ) on Friday January 23, 2009 @01:10PM (#26576563) Homepage Journal
      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.

      • Re: (Score:2)

        by Fred_A ( 10934 )

        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.

        Quite, I've had to refer to technical documentation from large entities such as IBM, Tandem, Sun and Microsoft and Microsoft just does a concictantly terrible job of it.

        While the others *did* have errors from time, they were rarely completely wrong, making stuff up, or just absent, which I've regularly seen happen with MS.

    • Re:When you have documentation (Score:4, Insightful)

      by DerekLyons ( 302214 ) <fairwater@@@gmail...com> on Friday January 23, 2009 @01:36PM (#26577051) Homepage

      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.

  • You just left the complicated and powerful interfaces undocumentes and left it to thick books to reverse-engineer and analyze them. When something was wrong, you blamed the external author.

  • Not MS's fault. (Score:5, Funny)

    by R2.0 ( 532027 ) on Friday January 23, 2009 @11:31AM (#26574883)

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

  • It was the best of times... (Score:5, Funny)

    by Anonymous Coward on Friday January 23, 2009 @11:31AM (#26574885)

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

    • IRQL_NOT_LESS_OR_EQUAL generates a STOP 0x0000000A error, not a stop 0x000000D1 error. You insensitive clod.

  • There's a few bugs in documentation generator [wikipedia.org] itself.

  • Questions (Score:5, Insightful)

    by BoneFlower ( 107640 ) <anniethebruce@ g m a i l . c om> on Friday January 23, 2009 @11:38AM (#26574949) Journal

    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.

    • If it's the latter, then the most obvious explanation: management prioritized adding new features in the next version over proper documentation, and programmers can't describe what they wrote 15 years ago (even if they have the source).

  • It seems pretty simple to me. More documentation, especially rushed documentation, is going to lead to more bugs. Not really Microsoft's fault, as long as they're attempting to minimize them and fix them as necessary.
  • "The number of bugs in technical documentation for Microsoft communication protocols continues to grow"

    Why don't they use the original specs the programmers used to implement the communication protocols on Microsofts' own server product?

    "Microsoft officials have also suggested that the number of bugs will rise as the company devotes more resources to identifying and fixing them"

    How does documentation get 'bugs', with access to the source and the developers it would be straight forward to get each p

    • Maybe the original developers aren't around anymore. That's not so unlikely. These programmers knew the specs. They wrote the implementation, they better do!

      But well, even programmers forget, so even if you DO have the same programmers around (who, btw, are probably by now far too valuable to waste them on something like documenting your product for someone you actually do NOT want to have documentation, i.e. a waste of money for the company), it's not necessarily a given that they could provide a bullet pr

    • Why don't they use the original specs the programmers used to implement the communication protocols on Microsofts' own server product?

      Well, specs may have errors too. You cannot test the specs like you test the code. So if specs have some bug (like, it does not cover some not-so-obvious situation) and developer notices this, there we can ask is the spec was updated, or it was "silencely" changed by the developer (it should not happen, but such things happen).

      Also, no matter that code is the only relevant source of information what was really implemented, it does not mean that every behavior is obvious from the code.

  • Comment removed based on user account deletion
  • Ok, here is my obligatory rant against MIS degrees. MIS graduates make lousy technical writers. They don't really understand computing architecture or software architecture, and it's difficult to hire and retain people who do who can also write clearly, and it's even HARDER to find good editors.

    Part of the problem is that if you are really good at tech writing, the allure of the secondary book market is too great. Why be on Microsoft's dime, which isn't probably very lucrative, when you could be publishin

    • Part of the problem is that if you are really good at tech writing, the allure of the secondary book market is too great.

      I think most of the problem is that many Computer Science programs seem to de-emphasize the importance of being able to write & communicate effectively. I've seen many technically brilliant software engineers who can't write a coherent (and grammatically correct) sentence, much less 20,000 pages of documentation. More courses focused on simply reading & writing would be enormo

    • Re: (Score:1)

      by maxume ( 22995 )

      I would bet a nickel that being employed with benefits is more alluring than writing for O'Reilly or SAMS. I would bet a dime that Microsoft is organizationally functional enough to provide good writers with adequate compensation (their organizational bankruptcy is internet-hater fiction, they are among the most profitable companies in the world, that doesn't come from being incompetent).

      I have read quite a few accounts of people who wrote technical books, and most of them say "I enjoyed it and it was worth

  • Various companies operate under various standards. IBM, for example, seems to be very rigid in every way when it comes to the way things are done, especially when it comes to the AS/400 series of products and services. So I wonder how much of Microsoft's culture is the point of failure [to meet expectations/demands] and not so much intent to deceive. I know that personally, I am a pretty scattered person. My stuff is fairly scattered and visually disorganized meaning that no one, other than myself, can

  • Microsoft's documentation may be bug ridden, but at least it is instantly available, easily searched and covers all their products.

    I've had the chance to work with other closed-source and opensource vendors, and none of them come even near the amount of documentation that is readily available on their website. Veritas' documentation just lacks the bugs their software has, and CA never heard about documentation.

    • Re: (Score:3, Interesting)

      by Almahtar ( 991773 )
      Try Qt. Their documentation is absolutely awesome. I worked with MSDN after working with Qt, and it was an eye opener.

  • I've always found them to be witten in obfuscatese. If I google for help and get a microsoft article and any other site matching the topic, the other site will prove far more useful.

    Something that irked me for years and years is how they don't bother to write a decent manual for their products anymore. You go and buy Office. You get a CD-ROM, yay. What about a manual? Well now, you must buy that separately from a different publisher. What the hell? Why can't Microsoft include the documentation with the orig

  • I'm currently porting from fortran to C++ an app that's been developed over the past ~30 years. The standard for the program's correct behavior is: whatever the program does.

    So the people who were supposed to document it before I started porting it had a Herculean task (or maybe a Sisyphean task). It's very hard to make intelligible and correct documentation, when the behavior of the program being documented is all over the place.

    I suspect Microsoft faces a very similar thing with their networking protoco

    • Re:I'm sympathetic (Score:4, Insightful)

      by Amazing Quantum Man ( 458715 ) on Friday January 23, 2009 @01:01PM (#26576409) Homepage

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

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

        How can you justify that? They seem to have gotten by just fine, until recently, with their approach. If you consider that this legal remedy came out of nowhere, form the developers' perspectives, then it's hard to argue with their success, at least w.r.t. SMB. Granted, it came bundled with Windows, so there wasn't much customer choice, but it still worked well-enough.

    • I'm currently porting from fortran to C++ an app that's been developed over the past ~30 years. The standard for the program's correct behavior is: whatever the program does.

      So why are you porting it? If it works properly, I'm sure there are Fortran compilers for whatever you want to run it on.

  • They could start.. (Score:4, Interesting)

    by OneSmartFellow ( 716217 ) on Friday January 23, 2009 @12:25PM (#26575623)
    .. 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
  • One of things I noticed when I started developing with Microsoft products (around 2003) was the strong community. You could usually find the answer to a technical question in a blog or forum or search engine query. .Net developer forums are generally helpful and not snarky, by my experience.

    My theory is MS management caught wind of this to the tune of: "Wow, all these do-gooders are documenting our products for us for FREE!!!...why should we pay employees to do this!???".

    ...Now I consistently see in
    • Yea, those are all fine and dandy if you're writing Windows apps that use MS protocols. However, I don't imagine they'd be too helpful if you popped up saying "I'm writing an open source alternative of (Microsoft Technology). (Section) of the protocol is a little unclear, could you specify in more detail?"

  • Why don't they release the docs *they* use? (Score:4, Funny)

    by Prototerm ( 762512 ) on Friday January 23, 2009 @12:41PM (#26575929)

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

    Oh, wait.

  • That's 464 bugs in a month. Eight hundred people can't close 464 bugs?

    -Peter

    • well it would depend on what the bug is, take a look at how long it takes them to fix some of the bugs that have been released, and if they just slap a patch out does it break something else. To me it makes sense that they get 464 bugs a month from their os's. just look at all the different types of hardware configs and software out there, to me I think that number is really low. And i know I'm going to get a troll status on this and a *nux users going to say thats why they have a crappy os, *nix has it fai

      • Also, even if these were OS bugs, I can't accept over a man-month on average to close a bug. An odd bug taking that long from time to time, maybe. But any system where that's the average is so fragile that it's not worth saving.

        -Peter

    • Re: (Score:2)

      by 0123456 ( 636235 )

      "Eight hundred people can't close 464 bugs?"

      Not when they don't know how their code works either :).

    • Nope. But they can introduce that many. Especially if they're new hires or new to the project.

  • Three day old bird SNARGE (look it up) is more interesting than this article. I have several points I would like to gripe about regarding Microsoft's technical help. But this article fails to be specific. Tech Net or MS Dev Net? What MS web sites? So I am not going to feed the Information Week rumor monster. I think that's an article designed to get information from unsuspecting slashdot and other users.

    Good bye, hrumpfh!
    Jim

  • The question is, how honest is their 800 number? What percentage of those 800 are non-technical administrative employees? How many managers has MS included in that number even though they don't, directly, contribute to the work? How many of the technical people are only able to apply a token amount of time to the process because they are shared with other projects? I would be interested in knowing how the courts are monitoring their numbers (if at all). Just because the number sounds high doesn't mean

  • fire everyone from the doc dept then...

Slashdot Top Deals

I tell them to turn to the study of mathematics, for it is only there that they might escape the lusts of the flesh. -- Thomas Mann, "The Magic Mountain"

Close