Quote:
Originally Posted by scottro
I've heard that from other programmers too--that their programming documentation is still pretty atrocious. Not being a programmer, I wouldn't know--their sysadmin stuff is often pretty useful though. At my old job, I remember one day, the Windows admin was out and we needed to do something, just typed a few words into help and it gave a nice page with examples, making it easy to do. Though I've not had to do any Windows administration in a year and a half, so I don't know the current state.
|
I wouldn't say atrocious but it's not good. Some disagree on this argument, but I attribute it partly to these javadoc-like embedded documentation extractors. They change the problem from thinking about what needs to be communicated, confronting an empty page, to plugging in smidgens of text in each of the required places, i.e. before each class and method. If someone's very diligent and weighs the result that may not be so bad. But normally what you have is a skeleton of documentation with important issues not addressed. And at the lowest points you have the same information that's in the class and method names, and no more, repeated with articles and prepositions added.
Then again Perl's documentation is often embedded (however, the flexibility is much greater so it doesn't all have to be) and I think it's fantastic (though how much does that have to do with a certain individual by the name of Tom Christiansen?). Maybe it's more only about how much the people writing it -- or the people paying the people writing it -- care. Obviously, when things are done only for commercial reasons you're back to a cost benefit analysis. Microsoft's documentation is probably now at the level of quality where putting more effort into it can't be justified in terms of increased profits.