Bugs In Microsoft Technical Documentation Rising 146
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."
I didn't know you could get sued for bugs. (Score:4, Insightful)
Re: (Score:1, Insightful)
Don't play the stupid card, it's pathetic.
They're not sued for bugs but for abusing their monopoly...
Re:I didn't know you could get sued for bugs. (Score:4, Insightful)
Don't play the stupid card, it's pathetic.
They're not sued for bugs but for abusing their monopoly...
whoosh
Shocked, shocked that there is gambing going on... (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.
Re:Shocked, shocked that there is gambing going on (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.
Re: (Score:2)
Well, then tell me what formats that are not "gotta do"s get implemented? Whenever there is any remote chance to ignore MS formats, they get ignored.
"Bugs"? (Score:5, Insightful)
Do they mean documentation shows bugs with Microsoft's communication protocols or that the documentation is incomplete or erroneous?
Re: (Score:1, Interesting)
Re: (Score:2, Insightful)
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.
Re: (Score:2)
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:2)
Try BSD man pages.
Re: (Score:3, Informative)
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)
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)
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)
When you have documentation (Score:5, Insightful)
Re: (Score:3)
Re:When you have documentation (Score:5, Insightful)
Re:When you have documentation (Score:5, Funny)
*waves hand*
This is not the documentation you're looking for.
Re: (Score:2)
I'm a Ballmerian. Mind tricks don't work on me! Only money.
Re:When you have documentation (Score:4, Insightful)
Re: (Score:3, Insightful)
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)
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.
Re: (Score:2)
And in specific, GP is also correct.
Re: (Score:2)
match up correctly with the other 19,975 pages the other 799 people are responsible for
I thought that's what templates were for...
Re: (Score:2)
Re:When you have documentation (Score:5, Insightful)
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)
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)
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.
Earlier it was easier. (Score:2)
Not MS's fault. (Score:5, Funny)
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)
...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
Re: (Score:2)
IRQL_NOT_LESS_OR_EQUAL generates a STOP 0x0000000A error, not a stop 0x000000D1 error. You insensitive clod.
The reason.. (Score:2)
Questions (Score:5, 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.
Re: (Score:2)
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).
More docs = more bugs (Score:2, Insightful)
Re: (Score:2)
Microsoft undocumentation .. (Score:2)
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
Re: (Score:2)
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
reason for bugs is the programmers are all dead :) (Score:2)
I would assume they would have use some kind of Revision Control System [wikipedia.org] and MS could hire on new programmers and give then access to that, yea ?
Re: (Score:2)
As long as it wasn't Source Safe, a product so bad I wouldn't even use it to store the Vista source code. Oh wait, I would because I'd want it to be lost.
Re: (Score:2)
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.
Re: (Score:1)
Computer Science Education (Score:2)
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
Re: (Score:2)
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)
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
Corporate culture plays into this I am sure (Score:2)
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
At least there is documentation! (Score:2, Funny)
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)
never liked the microsoft docs (Score:2)
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 sympathetic (Score:2)
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)
And therein lies the problem. MS should have created a spec for their networking protocols BEFORE implementing them.
Re: (Score:2)
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.
Re:I'm sympathetic (Score:4, 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.
Re: (Score:1)
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.
That's awesome.
Re: (Score:3, Interesting)
It may be awesome, but it's symptomatic of a poor development culture at MS, and ties back into the lack of protocol documentation.
Re: (Score:2)
They didn't produce SQL server, they bought Sybase [wikipedia.org].
Re: (Score:2)
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)
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
Blogs = Documentation? (Score:1)
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!???".
Re: (Score:2)
Why don't they release the docs *they* use? (Score:4, Funny)
They're in text files with a ".h" or a ".c" extension, right?
Oh, wait.
Math (Score:1)
That's 464 bugs in a month. Eight hundred people can't close 464 bugs?
-Peter
Re: (Score:1)
Re: (Score:2)
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)
"Eight hundred people can't close 464 bugs?"
Not when they don't know how their code works either :).
Re: (Score:2)
Non Informative Article (Score:2)
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
How honest are their numbers? (Score:2)
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
Maybe they shouldn't (Score:2)
Re:To the editors (Score:5, 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.
Re: (Score:2)
Yeah, can I have the corporate IT overlords here contact you about that?
Re:To the editors (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.
Re: (Score:3, Insightful)
You'd think, if Microsoft were a sensible company, they'd realise that not only might the engineers that made something (like a protocol or a library) not be there in the future, but they also might not remember every single detail of everything they've ever done for MS. Knowing this, it would follow they'd have some good internal documentation policies, and when courts say "give us the documentation", they could just hand over a great big pdf (or docx :P), and that would be the end of it. If this is the
Re: (Score:1, Offtopic)
Also, why reward that kind of behavior with massive visitor count increases, used in part to determine prices when selling ad space ?
Re: (Score:1)
Not everyone is in a position where they can install their own browser and/or extensions.
If your workstation has any location where you have write access, or if it has an available USB port, you can use Firefox Portable. No installation privileges needed (no registry writes), and very little trace if you run it from a stick.
http://portableapps.com/apps/internet/firefox_portable [portableapps.com]
Re: (Score:1, Offtopic)
I won't be doing that at work. My Corporate IT overlords are not amused by clever subversion of their security measures. This includes running 'portable' apps in an attempt to avoid detection. BTW, here they don't avoid detection, and I would get hammered for trying. My offshore dev teams can and do use Firefox to develop IE-specific apps, and are VPN'd into our network, but they have different rules. and apparently they also get paid by the bug only if reported out of warranty. But I'm not complainin
Re: (Score:3, Funny)
But I'm not complaining. I'm working.
So your job is to sit around and post on Slashdot, then?
Re: (Score:2)
My job includes "other tasks as required".
In between, I do what is not required.
Re: (Score:2)
Pop up blockers aren't really fair, a lot of webmasters rely on ad revenue to prop up free services.
No, the answer is not to visit sites whose user's are nothing more to them than a unique IP.
Re: (Score:2)
No, they are very fair.
A good site designer can put up advertisements without being obtrusive, forcing me to look at ads or throwing ads in my face. For an example of this, look at Google's advertisements. They are barely noticeable. As a result, they are not in my list of "Adblocked" ads.
What is not fair is forcing stupid "CLICK THE MONKEY!!!!" advertisements. Or forcing me to click through multiples pages just so I see more ads.
Re: (Score:1)
GUID's are EVIL
Re: (Score:3, Interesting)
And then telling other people to stop whining and just install a shitblocker.
Yes I know ads aren't that bad (normally anyway).
just don't go eat there to eat? ... (Score:2)
And ads can sure smell as bad ...
Re: (Score:2)
Shitblocker gives you a 404 when you try to go to 2 girls 1 cup.
Re: (Score:2)
Where can I download it?
Re: (Score:1)
Re: (Score:2)
I think this could be a delaying tactic by Microsoft.
What, the buggy documents, or the whining about infoworld?
Re: (Score:2)
That depends if you're a deceased French philosopher.
Re: (Score:2, Funny)
I thought everyone here was using an Adblocker by now?
---
Selectively add free since 2003...
Re:To the editors (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???
Re:To the editors (Score:5, Funny)
Re: (Score:3, Interesting)
Print view [infoworld.com]
I would contend that all articles should link to the print preview if the article has obnoxious ads or superfluous page breaks, but then they'd just stop providing print views.
Keep this to yourselves. ;)
Re:To the doofus (Score:2)
I dunno what web browser you are using, but if you run Firefox, with standard script and visual-spam control, you don't see any images on that page except three, 2x2cm thumbnails for some videos on the lower part of the right column.
What browser are you using?
Quit using IE Re:To the editors (Score:2)
Says it all doesn't it?
Re: (Score:1, Funny)
It's as easy as:
troll-get update && troll-get upgrade
Voila problem solved!
Re:Wonderful (Score:4, 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.
Re: (Score:2)
I once reprimanded a intern programming student for following the MSDN example code. There is something wrong with saying to someone: "I know you know that Microsoft example code does not work. You can tell by just looking at it."
There is something wrong about needing to teach young programmers to not follow the Microsoft documentation. Even after 10 years, Microsoft still hasn't went back and fixed the documentation either. They just created more API's with more documentation problems.
Re: (Score:2)
If you only review one page a week, even taking into account an astronomical 1/2 of the people "working" on this as managers who do absolutely nothing, this should be cleared up well within the time frame that this has been going on.
They keep having to try to get rid of clippy.