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."
Please stop posting articles from info world. The have ads after every page of the article and obtrusive on page overlays.
Thanks.
I better write some more unit tests...
... ... ... ...
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?
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
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.
CreateWindow - This method is used to create a window.
Now here's a half-dozen parameters each comprising about a gazillion combinations with such helpful narrative as:
WS_THICKLINE - this draws a border with a thickline.
Thank you for spending $300 on MSDN!
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
A mistake in code that causes improper function is colloquially called a "bug".
A mistake in technical documentation is either a typo, or a flat-out error.
Stop referring to everyday mistakes as "bugs"! It seriously makes you sound elitist not smarter.
So "bugs" it has to remain. That is merely accidental errors. Incomplete means MS are breaking the agreement and erroneous means that MS are telling lies about the protocols.
So "Bugs" it is.
Kind of makes you wonder how many of those people they had to let go recently would still be able to be employed if Microsoft didn't have to task 800 employees to comply with these states' demands. No matter how you try to explain it away, that is a lot of overhead cost. I'm not saying that they wouldn't have laid off some people, but rather that their numbers might have been close enough to their estimates that their management might not have felt much pressure to cut costs.
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"?
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.)
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
"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)
That's 464 bugs in a month. Eight hundred people can't close 464 bugs?
-Peter
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 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
The general consensus is that documentation is not that important; getting the product out the door so you can generate cashflow is. In effect, the belief is that documentation doesn't pay the bills.
The problem is exacerbated by code monkeys who see documentation as unimportant. They know what they're doing,so who cares. But that's no the real problem.
The fact is that docs should be an integral part of development and where that policy is enforced, the future becomes happier for everyone. But it requires discipline and commitment from management in particular because they are the ones responsible for the mess we are in because they have the power to change the situation.
A friend is in charge of maintaining the code base for a call center. When he began enforcing a requirement to document as you code and made it a priority, life was better for all concerned, so it can be done,
Sounds like they need to do some hiring and help out with this recession. I'm only partially kidding...
So, let me get this straight, you have 800 people working on correcting 20,000 pages of documentation. That works out to 25 pages per person. I'm not sure how long they've been "working" on this but it seems that they are at best ineffective.
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.
In related news, nearly 800 Microsoft employees working on technical documentation were among the 5,000 layed off yesterday.
Their tech writers only have to maintain 25 pages each? So they each have to fix a little more than 2 bugs each. So we should have all of this resolved by tomorrow, right?
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.
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.
fire everyone from the doc dept then...
Why do I have the sneaking suspicion that those assigned to work on this task may not be M$ best and brightest.
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
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..
I actually think I feel bad for Microsoft in this case, or at least for the people that have to work on the docs.
I would expect, in MANY cases, Microsoft did not have an actual defined wire protocol, they had one client product & one server product that they just built to work together. No defined wire protocol, no documentation. In these cases, these poor saps would have to write docs from scratch, basically having to write docs that just match the behavior of some blob of code, and keep reworking the docs until they match the code behavior. I do not envy them at all.
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.