×

Welcome to the Slashdot Beta site -- learn more here. Use the link in the footer or click here to return to the Classic version of Slashdot.

Thank you!

Before you choose to head back to the Classic look of the site, we'd appreciate it if you share your thoughts on the Beta; your feedback is what drives our ongoing development.

Beta is different and we value you taking the time to try it out. Please take a look at the changes we've made in Beta and  learn more about it. Thanks for reading, and for making the site better!

Bugs In Microsoft Technical Documentation Rising

kdawson posted more than 5 years ago | from the costs-of-monopoly dept.

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

cancel ×
This is a preview of your comment

No Comment Title Entered

Anonymous Coward 1 minute ago

No Comment Entered

146 comments

***Security warning!!!*** (-1, Troll)

Jor-Al (1298017) | more than 5 years ago | (#26574701)

Bugs in ninnle linux have been found that may cause millions of vibrators to explode. Please upgrade your copy of ninnle linux!

Re:***Security warning!!!*** (1, Funny)

Anonymous Coward | more than 5 years ago | (#26575001)

It's as easy as:

troll-get update && troll-get upgrade

Voila problem solved!

To the editors (0, Offtopic)

Zebra_X (13249) | more than 5 years ago | (#26574705)

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

Thanks.

Re:To the editors (4, Informative)

bogaboga (793279) | more than 5 years ago | (#26574775)

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:To the editors (0)

Anonymous Coward | more than 5 years ago | (#26574945)

When you change the channel, does the war in Iraq or the genocide in Darfur cease to exist?

Re:To the editors (0)

Anonymous Coward | more than 5 years ago | (#26575095)

Yes it does, at least for me. Me choosing to, or not to watch it on TV has absolutely ZERO effect on what happens on a daily basis or the final outcome.

Re:To the editors (0)

Anonymous Coward | more than 5 years ago | (#26575205)

Genocide in another country is no concern of mine. If they want to stop the genocide, feel free to have a revolution.

Re:To the editors (0)

Anonymous Coward | more than 5 years ago | (#26575391)

When you change the channel, does the war in Iraq or the genocide in Darfur cease to exist?

Don't respond to offtopic trolls.... nhaaa...

Well, you can move to these places to solve the problems. And once you have solved them, you can come back here to report how you have done it. In the meantime STFU.

Re:To the editors (5, Insightful)

truthsearch (249536) | more than 5 years ago | (#26575305)

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:To the editors (0, Offtopic)

ianare (1132971) | more than 5 years ago | (#26575471)

Not everyone is in a position where they can install their own browser and/or extensions.
Also, why reward that kind of behavior with massive visitor count increases, used in part to determine prices when selling ad space ?

Re:To the editors (0)

Anonymous Coward | more than 4 years ago | (#26575595)

Use Portable Firefox (http://www.portableapps.com). Apply an IE theme if you want to fool the casual observer.

Re:To the editors (0, Offtopic)

rickb928 (945187) | more than 4 years ago | (#26575827)

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 complaining. I'm working.

ps- Not so annoying as getting Infoworld on my G1. Waiting while the ads load just to unload. Pus.

Re:To the editors (2, Funny)

D Ninja (825055) | more than 4 years ago | (#26576441)

But I'm not complaining. I'm working.

So your job is to sit around and post on Slashdot, then?

Re:To the editors (1)

BForrester (946915) | more than 4 years ago | (#26577403)

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:To the editors (1)

lukas84 (912874) | more than 4 years ago | (#26578785)

This, of course, assumes that you can execute programs from any location, which shouldn't be the case in a proper corporate environment.

Re:To the editors (1)

EddyPearson (901263) | more than 4 years ago | (#26575769)

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:To the editors (1)

D Ninja (825055) | more than 4 years ago | (#26576477)

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:To the editors (-1, Troll)

Anonymous Coward | more than 4 years ago | (#26576341)

Firefox is slow and bloaty, especially with ad-blockers installed.

Re:To the editors (2, Interesting)

TheLink (130905) | more than 4 years ago | (#26576829)

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

Re:To the editors (1)

NicknamesAreStupid (1040118) | more than 4 years ago | (#26576981)

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

Re:To the editors (0)

Anonymous Coward | more than 4 years ago | (#26577085)

What the hell is an improperly installed ad-blocker extension supposed to be? Do you feel special, being able to click a button?

Re:To the editors (1)

clarkn0va (807617) | more than 4 years ago | (#26577769)

I think this could be a delaying tactic by Microsoft.

What, the buggy documents, or the whining about infoworld?

Re:To the editors (2, Funny)

Anonymous Coward | more than 5 years ago | (#26574799)

I thought everyone here was using an Adblocker by now?
---
Selectively add free since 2003...

Re:To the editors (0)

Anonymous Coward | more than 4 years ago | (#26575697)

+ Noscrtipt, didn't see any ads

Re:To the editors (5, Funny)

jonaskoelker (922170) | more than 5 years ago | (#26574931)

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 (0)

Anonymous Coward | more than 4 years ago | (#26575625)

Yes, indeed. That is how the website earns enough money to stay going. Because not all of us can make available high amounts of high quality news and spend a lot of time into it by just "blogging on our free time as a hobby. There are loads of people doing it."...

The resources must come from somewhere. Have *you* donated to the site's owners? I doubt that. I haven't either. And I doubt very few of rest of the people here have either. A lot less ads on the internet = a lot less high quality content because a lot less people have interest in producing it.

You have full rights and are doing anything even morally questionable by choosing just not to go on such sites. You are within your legal rights to use adBlocker. (And while I personally deem it morally questionable, I won't start arguing it here as that would quickly degrade into a flamewar)

On the contrary, however, some of us are perfectly willing to watch a couple of ads and occasionally click if we see anything even mildly interesting if it helps to support the websites that have interesting content.

(that all said... Yeah, some of those ads were a bit annoying. But I can't avoid feeling rage when every other day I see slashdotters comment "Bwaa, the website you linked has ADS!" and others reply "Well, just block the ads like the rest of us")

Re:To the editors (0)

Anonymous Coward | more than 4 years ago | (#26577019)

Please look at the links you are about to click on and choose, as I do, to not click on links to infoworld.com

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

Thanks.

Re:To the editors (2, Interesting)

Thaelon (250687) | more than 4 years ago | (#26577575)

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

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

kbrasee (1379057) | more than 5 years ago | (#26574761)

I better write some more unit tests...

Re:I didn't know you could get sued for bugs. (1, Insightful)

Anonymous Coward | more than 5 years ago | (#26575029)

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. (4, Insightful)

kbrasee (1379057) | more than 5 years ago | (#26575115)

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... (4, Interesting)

cwAllenPoole (1228672) | more than 5 years ago | (#26574783)

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

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 (5, Insightful)

Opportunist (166417) | more than 5 years ago | (#26575123)

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.

"Bugs"? (5, Insightful)

Anonymous Coward | more than 5 years ago | (#26574791)

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

Re:"Bugs"? (2, Interesting)

cosam (460350) | more than 5 years ago | (#26575049)

They were obviously instructed to produce documentation that accurately reflects their software. So that would be latter...

Re:"Bugs"? (2, Insightful)

morgan_greywolf (835522) | more than 5 years ago | (#26575489)

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.

Only MS knows which (0)

Anonymous Coward | more than 5 years ago | (#26575063)

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.

Re:"Bugs"? (2, Informative)

jonaskoelker (922170) | more than 4 years ago | (#26575865)

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:"Bugs"? (2, Informative)

ryry (198300) | more than 4 years ago | (#26576535)

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

A million monkeys @ a million typewriters (-1, Flamebait)

Anonymous Coward | more than 5 years ago | (#26574853)

Further proof that a million code-monkeys at a million glorified typewriters, will eventually produce something.

Through enough excrement, and some of it will actually compile, and a product will come out.

This is what Microsoft refers to as "push" technology when they "push" out a new turd, I man product.

When you have documentation (5, Insightful)

El Lobo (994537) | more than 5 years ago | (#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:When you have documentation (2)

El Lobo (994537) | more than 5 years ago | (#26575031)

Oh NOWWWWWW i get it. The editor was the dear KDAWSON. Now everything is clear.

Re:When you have documentation (5, Insightful)

Yvanhoe (564877) | more than 5 years ago | (#26575059)

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 (3, Insightful)

El Lobo (994537) | more than 5 years ago | (#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:When you have documentation (2, Insightful)

D Ninja (825055) | more than 4 years ago | (#26576531)

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 don't even know where to begin.

Re:When you have documentation (0)

Anonymous Coward | more than 4 years ago | (#26578353)

You might not know, Fortran 90/95 is actually much more readable compared to C or Perl.

There are as many dialects of C as C coders (and C++ is worse), while in Fortran there are maybe 2-3 ways to do something. Which is a good thing for the compiler and your fellow coders.

But well, to slashdot Fortran is still ALL CAPS OMG!1!!!111!

Re:When you have documentation (3, Insightful)

truthsearch (249536) | more than 4 years ago | (#26575545)

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:When you have documentation (1)

Americano (920576) | more than 4 years ago | (#26576677)

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 with the behavior of the actual software.

Anybody who would claim that this is not a significant amount of work, or that it should be "easy" because each person is only responsible for 25 pages is either completely unfamiliar with software development, or a fool who thinks that simply throwing more people at a large problem makes it trivial to accomplish.

Re:When you have documentation (1)

nschubach (922175) | more than 4 years ago | (#26577071)

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:When you have documentation (1)

Americano (920576) | more than 4 years ago | (#26577213)

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 (4, Insightful)

fermion (181285) | more than 4 years ago | (#26576563)

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:When you have documentation (3, Insightful)

DerekLyons (302214) | more than 4 years ago | (#26577051)

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.

Earlier it was easier. (1)

drolli (522659) | more than 5 years ago | (#26574877)

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. (5, Funny)

R2.0 (532027) | more than 5 years ago | (#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... (5, Funny)

Anonymous Coward | more than 5 years ago | (#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

Re:It was the best of times... (0)

Anonymous Coward | more than 4 years ago | (#26575679)

You need a faster internet connection! That DateStamp is Thu Jul 03 19:49:27 2003 (EST), which means your latency is about 5.5 years!

Re:It was the best of times... (0)

Anonymous Coward | more than 4 years ago | (#26577729)

Nah it was just another bug.

Questions (4, Insightful)

BoneFlower (107640) | more than 5 years ago | (#26574949)

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:Questions (1)

dkleinsc (563838) | more than 4 years ago | (#26575683)

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

Re:Questions (0)

Anonymous Coward | more than 4 years ago | (#26578709)

Come now, don't let your logic get in the way of a good MS bashing!

More docs = more bugs (2, Insightful)

DeadPixels (1391907) | more than 5 years ago | (#26574963)

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.

Bugs like (0)

Anonymous Coward | more than 5 years ago | (#26574983)

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!

Microsoft undocumentation .. (1)

rs232 (849320) | more than 5 years ago | (#26575021)

"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 [edge-op.org] information, I would suspect this as yet more Microsoft undocumentation [sonic.net]

Re:Microsoft undocumentation .. (1)

Opportunist (166417) | more than 5 years ago | (#26575273)

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 proof documentation of all little quirks.

So you have the source. That's nice. Unless you put some rather new programmers at the project (remember: waste of money) who are not in touch with the Tao of programming (as little as there may be in the code) and don't have the foggiest idea what the hell someone meant when they coded something (and documented it poorly, maybe not at all, maybe just with in-code comments that may or may not be outdated and not in sync with the actual code anymore). Add on top of that, that the code most likely has been changed and rewritten a few times until some structures don't make a lot of sense anymore and you end up at a veritable nightmare to document.

reason for bugs is the programmers are all dead :) (1)

rs232 (849320) | more than 4 years ago | (#26575773)

"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 [wikipedia.org] and MS could hire on new programmers and give then access to that, yea ?

Re:Microsoft undocumentation .. (1)

saigon_from_europe (741782) | more than 4 years ago | (#26575803)

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.

Wonderful (0)

Anonymous Coward | more than 5 years ago | (#26575043)

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.

Re:Wonderful (3, Informative)

pjt33 (739471) | more than 5 years ago | (#26575077)

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

Just a thought... (0)

MikeRT (947531) | more than 5 years ago | (#26575089)

Nearly 800 Microsoft employees are working on the more than 20,000 pages of technical documentation, according to the court documents filed Wednesday

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.

Computer Science Education (1)

GPLDAN (732269) | more than 5 years ago | (#26575171)

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"?

Re:Computer Science Education (1)

Americano (920576) | more than 4 years ago | (#26577017)

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 enormously helpful as a CS curriculum requirement.

Writing excellent software requires that you know the language you're writing in, and know how to apply that language to the problem you're trying to solve. Writing excellent documentation is the same - part training, part practice.

Re:Computer Science Education (1)

maxume (22995) | more than 4 years ago | (#26577543)

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 it", but they also say "don't do it if you think you are going to make a lot of money".

Corporate culture plays into this I am sure (1)

erroneus (253617) | more than 5 years ago | (#26575291)

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

At least there is documentation! (2, Funny)

wouter (103085) | more than 5 years ago | (#26575307)

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.

never liked the microsoft docs (1)

jollyreaper (513215) | more than 4 years ago | (#26575499)

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.

I'm sympathetic (1)

DoofusOfDeath (636671) | more than 4 years ago | (#26575527)

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.

Re:I'm sympathetic (3, Insightful)

Amazing Quantum Man (458715) | more than 4 years ago | (#26576409)

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

Re:I'm sympathetic (1)

DoofusOfDeath (636671) | more than 4 years ago | (#26577291)

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 (3, Interesting)

Amazing Quantum Man (458715) | more than 4 years ago | (#26577699)

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:I'm sympathetic (1)

DoofusOfDeath (636671) | more than 4 years ago | (#26577803)

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:I'm sympathetic (2, Interesting)

Amazing Quantum Man (458715) | more than 4 years ago | (#26578627)

It may be awesome, but it's symptomatic of a poor development culture at MS, and ties back into the lack of protocol documentation.

They could start.. (3, Interesting)

OneSmartFellow (716217) | more than 4 years ago | (#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

Blogs = Documentation? (1)

flanders123 (871781) | more than 4 years ago | (#26575899)

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 incomplete and buggy API documentation in newer MS products (Commerce Server, and Sharepoint, if you must know).

Re:Blogs = Documentation? (1)

The Moof (859402) | more than 4 years ago | (#26576971)

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? (3, Funny)

Prototerm (762512) | more than 4 years ago | (#26575929)

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

Oh, wait.

Math (1)

pete-classic (75983) | more than 4 years ago | (#26576779)

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

-Peter

Re:Math (1)

xenolion (1371363) | more than 4 years ago | (#26577527)

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 fair share of bugs, just not as documents and ordered by a court to see all of them.

Re:Math (1)

0123456 (636235) | more than 4 years ago | (#26577675)

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

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

Non Informative Article (1)

JavaManJim (946878) | more than 4 years ago | (#26576841)

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? (1)

GameMaster (148118) | more than 4 years ago | (#26577381)

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.

If Docs are Neglected, Management is to Blame (0)

Anonymous Coward | more than 4 years ago | (#26578479)

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,

Ineffective (0)

Anonymous Coward | more than 4 years ago | (#26578569)

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... (0)

Anonymous Coward | more than 4 years ago | (#26578619)

In related news, nearly 800 Microsoft employees working on technical documentation were among the 5,000 layed off yesterday.

Load More Comments
Slashdot Account

Need an Account?

Forgot your password?

Don't worry, we never post anything without your permission.

Submission Text Formatting Tips

We support a small subset of HTML, namely these tags:

  • b
  • i
  • p
  • br
  • a
  • ol
  • ul
  • li
  • dl
  • dt
  • dd
  • em
  • strong
  • tt
  • blockquote
  • div
  • quote
  • ecode

"ecode" can be used for code snippets, for example:

<ecode>    while(1) { do_something(); } </ecode>
Sign up for Slashdot Newsletters
Create a Slashdot Account

Loading...