4 ms·
Judge: Microsoft documentation unfit for US consumption
- gruseom 18y agoUnfortunately, the company has consistently had trouble with producing complete and useful documentation. "Producing complete and useful" documentation is a huge amount of work - a nontrivial fraction of writing the software in the first place. It gets exponentially harder as the software gets more complicated and crappier. Actually, "complete documentation" is an oxymoron. The only complete specification of what code does is the code itself, so it will always be possible to find gaps. I'd be interested to know the specific inadequacies being cited here, but don't have time to follow the links. (If anyone else does, please post your findings.) Most developers find Microsoft's API documentation to be pretty good As someone who endured it for a long time, I'd vociferously dispute this. Their documentation is wildly uneven. The real problem, though, is that the APIs themselves are mostly terrible - way too complicated and not designed for the programmer who actually has to use them. (Portions of the .NET framework are an exception.)
- ComputerGuru 18y agoI felt the same way, until I tried coding on Mac. Believe me, if Apple ever got big enough to warrant government inspection, they'd get torn to shreds. Have you ever tried to see how OS X works under the hood? Hooked into the OS at boot level? Tried to modify low-level procedures?
- gruseom 18y agoNo, I haven't. And I take your point that things usually aren't any less chaotic on the other side of the fence. The vast majority of code everywhere is a mess; APIs only reflect that. It's a wonder that things work to the extent that they do.
- qhoxie 18y agoThe people that make things work are the same one's that have no problem with reading through the code. It's no coincidence.
- noodle 18y ago>>"Producing complete and useful" documentation is a huge amount of work - a nontrivial fraction of writing the software in the first place. this is definitely true, but does that somehow mean that bad documentation should be the norm or otherwise excused?
- gruseom 18y agoNo it doesn't, and my intention is not to make excuses (least of all for MS) - just to point out that the people ordering them to produce this probably don't understand what it is that they're ordering, that the task itself is either unsatisfiable or nearly so, and that it will probably consume orders of magnitude more resources than people expect. It's one of those things where you can't ever be "done" - especially if the other party has an interest in picking holes. Personally, I'm fine with MS having to lie in (or document every molecule) of the bed they made. The sooner we can all move beyond what they did to our industry the better.
- tptacek 18y agoI actually really like the network protocol documentation that Microsoft released; compare it, for example to Luke Leighton's CIFS book, which was the gold standard for a long time. I've implemented against Microsoft's protocol docs and not had much of a problem. You're right that the real issue here is that much of this stuff wasn't designed to be documented or published.
- rbanffy 18y ago"Producing complete and useful documentation is a huge amount of work" One would imagine such documentation already exists in one form or the other. I suppose their developers get trained somehow other than reading the source. In the end, if it is too hard to provide documentation, they can always open up the small parts of the code that implements such interfaces for others to use.