On 4/13/2011 23:45, Warp wrote:
>    Some companies are not that lazy. For example Apple has very extensive and
> ample documentation on their development environments (in the form of
> tutorials and reference manuals).

MS didn't *used* to be that bad. The XNA stuff just seems particularly 
poorly documented, like it's not really strategic or something. The blog 
posting is great. Detailed, examples, etc. Why the heck not copy it into the 
documentation for the routine, instead of seeing "go see the blog post at 
the URL for details of how to use this call"? (Of course, the answer is 
probably that someone would have to translate it, get it approved by 
lawyers, etc.)

Most of the MS documentation is pretty good, really, but it has indeed been 
going downhill.

>    Of course then there are those who either have no documentation to
> speak of, or just some lazy barely documented doxygen-generated listing
> of classes (which is often a couple of versions older than the most recent
> distribution of the library). Yes, I have concrete experience of exactly
> this.

That's my complaint. Maybe it's just the XNA stuff, but most of it is 
doxygen not-very-commented stuff, with third-party forums and blogs filling 
in.  I think I just grew up in a time frame when learning about computers 
came from books, so surfing around the whole world trying to guess the right 
keywords to see who already solved your problem is annoying. I mean, I 
learned APL by sitting down and reading the manual for the APL interpreter. 
Are you really going to learn something like Ruby from scratch by reading 
nothing but the documentation that comes with the interpreter? Hell, even 
the "official" Ruby book has statements in it that say things like "It seems 
to work like this..."  (That's when I gave up on Ruby, incidentally - when I 
realized the guy writing the O'Reilly book was guessing how it actually worked.)

Especially when there's like 4 or 5 versions (and half a dozen CTP and RC 
versions) in the last 4 years, and all the old posts are still hanging 
around, most of which don't mention what version they're using.

-- 
Darren New, San Diego CA, USA (PST)
   "Coding without comments is like
    driving without turn signals."

Post a reply to this message