Slashdot Mirror
Bugs In Microsoft Technical Documentation Rising
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 better write some more unit tests...
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.
... ... ... ...
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/
Do they mean documentation shows bugs with Microsoft's communication protocols or that the documentation is incomplete or erroneous?
I thought everyone here was using an Adblocker by now?
---
Selectively add free since 2003...
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!!
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.
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
...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
Please stop posting articles from info world. The have ads after every page of the article
O_o How do you know this???
There's a few bugs in documentation generator itself.
One of our competitors trademarked the term "hypothesis". From now on, we will call them "boneheaded ideas".
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.
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.
It's as easy as:
troll-get update && troll-get upgrade
Voila problem solved!
"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 programmer to write up a high-level description of what each function does, gather that into a spec, and voilà, there's your documentation already.
. If the company had a history of hiding information, I would suspect this as yet more Microsoft undocumentation
davecb5620@gmail.com
Yeah, can I have the corporate IT overlords here contact you about that?
Slightly disreputable, albeit gregarious
I once copy-pasted some demo code from MSDN and it didn't work. That's a bug in documentation even by your standards.
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.
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 publishing for Tim O'Reilley or SAMS? Why write solid O/S documentation, when you can write "The very super Windows Vista bible"?
You're not supposed to RTFA, idiot!
43 - For those who require slightly more than the answer to life, the universe and everything.
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 find anything easily. And when it comes to updating documentation? Well, I don't want to relate it to weather patterns in hell, but it is safe to say that for me to be motivated to update documentation, one of two condition must occur: 1) I am lost in my own mess and it just becomes too much even for me or 2) there is something else I would rather not be doing and updating documentation gets pushed up in priority as a result.
If Microsoft were like a whole bunch of ME (and I really hope that is not the case, but it would explain so much) then perhaps they aren't as malicious as they are painted to be in every single way? (But when it comes to "business strategy" and all things involving lawyers, they ARE evil. I am completely convinced of that.)
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.
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.
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 original software? It seems like they're only half-completing the action.
Something else I'd also like to see is the next step in documentation, making it more tightly integrated with the application. Often you look up something in documentation and are still struggling to find where the tool is beneath the menu trees. Often the exact method for performing the steps is less than obvious. What would be interesting is if they could include a proper "show me how this works" script to walk you through the actions. I've seen some try to do this but it just isn't quite right.
The other thing that's annoying is how the help window pops up in a separate window that requires a lot of real estate to open up properly. It's not quite as onerous with a dual-monitor system since I can have the help open on the side window but anyone with a single-window system is stuck trying to juggle them with alt-tabs.
On Windows, the fundamental interface paradigm hasn't changed much since 95. I'm not quite sure what the perfect solution would look like but the current way of doing things does seem to be rather inadequate. If Microsoft could figure out a way to do the whole help thing smarter, make the software act as a tutor for using it, allow even non-techie folks to figure out new features, then they could really justify selling the next version of Office.
Kwisatz Haderach
Sell the spice to CHOAM
This Mahdi took Shaddam's Throne
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 protocols, or with SMB at the very least.
.. 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
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.
You feel sleepy. Close your eyes. The opinions stated above are yours. You cannot imagine why you ever felt otherwise.
"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!"
I would assume they would have use some kind of Revision Control System and MS could hire on new programmers and give then access to that, yea ?
davecb5620@gmail.com
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.
...Now I consistently see incomplete and buggy API documentation in newer MS products (Commerce Server, and Sharepoint, if you must know).
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!???".
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)
GUID's are EVIL
But I'm not complaining. I'm working.
So your job is to sit around and post on Slashdot, then?
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.
That's 464 bugs in a month. Eight hundred people can't close 464 bugs?
-Peter
That's almost like continuing to eat at a restaurant that serves you food with shit on it just because you have "shitblocker" extension installed.
And then telling other people to stop whining and just install a shitblocker.
Yes I know ads aren't that bad (normally anyway).
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
"Never attribute to malice that which can be adequately explained by stupidity," Hanlon. The wheels started coming off this cart when Gates began fading from the picture. It was true for Ford, IBM, Compaq, Novell, and many others too. Until there is a new focus, these lapses will just get worse. Company Founders set the tone, and the company goes tone deaf when they leave. Some transcend the loss and move on while others founder.
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 it's a true gauge of how much effort they're putting in.
Rules of Conduct:
#1 - The DM is always right.
#2 - If the DM is wrong, see rule #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
Print view
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. ;)
Question everything
I think this could be a delaying tactic by Microsoft.
What, the buggy documents, or the whining about infoworld?
I am literally 3000 tokens away from the chaotic crossbow --Stephen
Sounds like they need to do some hiring and help out with this recession. I'm only partially kidding...
This, of course, assumes that you can execute programs from any location, which shouldn't be the case in a proper corporate environment.
My job includes "other tasks as required".
In between, I do what is not required.
deleting the extra space after periods so i can stay relevant, yeah.
Or does this paint a picture of lots of M$ employees on the SS Microsoft desperately using a chain of buckets to scoop water overboard as the ship sinks, complete with a chair shaped hole in the cabin window and an enraged bald man throwing a hissyfit inside?
.doc to close to 100% (for most users) it provides a loophole in Microsoft's vendor lock in strategy, so the solution is to fuck with the format, make sure it's not documented and pass the update to their own office suite. If it wasn't for the constant moving of the goalposts, they no doubt could document and provide a decent standard (even if it is patent encumbered and proprietary) which would let them easily submit the documentation they are struggling with now.
Microsoft don't want to have to release documentation, that would allow others to make their software more compatible with Microsoft formats, which weakens the vendor lock in obsession they have. They are only reluctantly releasing half arsed documentation to try and avoid even more fines, they don't want those documents to actually be of any use. They want people to be trawling through books of crap to get to the details. They want to casually "forget" some key elements. The last thing they need is people actually forcing Microsoft to fix the documentation so they are useful, it defeats the original plan. Look at the crap they submited for OfficeOpenXML filed under the usual "don't worry if it's a bit messy, we promise to clean it up AFTER you make it a standard." tag.
It was like the truck of Iraqi WMD documentation offered at the last minute to stave off a pre-destined invasion.....mostly fluff and bullshit aimed as a PR move (look, we're the good guys, we're complying, it's the nasty regulators who are trying to bully us).
Microsoft seem hell bent on focussing all their efforts on lobbyists and lawyers than actually making their products something people WANT to buy. I believe the main reason for all the shit with the formats spec changing is to keep one step ahead of proper interoperability. As the OSS peeps reverse engineer the latest
Remember this is stuff they are doing ONLY under orders from a judge with threats of fines for non-compliance. This is the proverbial kid being dragged down to someone's house by their parents and being forced to apologise, when they clearly think they've done nothing wrong.
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 state of their real internal documentation, I'd hate to think what problems it would cause when trying to make new technologies backwards compatible. As much as I'd like to think that Linux is winning on it's own merit, and proprietary software is collapsing, that's really only a tiny bit of the story. Microsoft are suffering not because of Linux, but because of broad-sweeping incompetence like this. Let's hope those 5000 layoffs make the remaining employees a little more wary about their job security, and make them work to prove their value to Microsoft.
Admit it. You post strawman arguments as AC so you get modded Insightful for refuting them, rather than Troll
That depends if you're a deceased French philosopher.
Nick
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.
It is difficult to get a man to understand something when his job depends on not understanding it.
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.
You are in a maze of twisty little passages, all alike.
Shitblocker gives you a 404 when you try to go to 2 girls 1 cup.
Random Thoughts From A Diseased Mind (Not For Dummies)
fire everyone from the doc dept then...
Where can I download it?
Why do I have the sneaking suspicion that those assigned to work on this task may not be M$ best and brightest.
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.
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?
Says it all doesn't it?
I'd go on a Vegan diet but the delivery time from Vega is too long. --brownkitty
We have at all times had a documentation system at MS to do exactly that. The problem is that it has been messed around with, upgraded, changed, politicised, etc so often, that getting reliable info out of it to code to is harder than just tracing the relevant source and doing it yourself. This, of course, introduces new bugs which are not documented either. I've been pushing to scrap the whole damned mess and create an internal wiki but you know what institutional inertia is like.
And ads can sure smell as bad ...
--- I am known for the ones who want to find me on the net. Is that a privacy risk or a privilege? One might wonder..
So don't implement MS formats. That's where the standards come in in the first place. There are some "gotta do"s like SMB, but wherever possible just ignore their obscure proprietary formats.
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.
We used to have a Bill of Rights. Now, with the rights gone, all we have left is the bill.
That's the price we all pay to get free content. Be thankful the Internet isn't run by cable companies. Oh wait ....
Seeing as Microsoft has a monopoly on the computer industry (albeit one which is slowly losing power thanks to apple), They don't have to worry about keeping their users happy. They have so many that they can afford to lose some to Macs or Linux distributions.
The mac OS is designed to run on a Mac PC, which means that the hardware is restricted and can only be bought from certified Apple resellers. You can't custom build a Mac out of parts from your local PC store either. And they cost more than a basic, 512MB RAM, windows XP computer.
And just the word Linux will scare many a Windows user. Words like 'compile' and phrases like 'sudo apt-get update' are likely to confuse and cause people to get angry.
So with no competitors who stand a chance of putting them out of business in the foreseeable future, they can do as they please and don't have to worry about properly servicing or listening to their end users.
Our culture doesn't get smarter, it just finds new ways of being retarded.