

Judge: Microsoft documentation unfit for US consumption - qhoxie
http://arstechnica.com/news.ars/post/20080925-judge-microsoft-documentation-unfit-for-us-consumption.html

======
gruseom
_Unfortunately, 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.)

~~~
noodle
>> _"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
No 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.

