On 14/04/2011 17:25, Darren New wrote:

> MS didn't *used* to be that bad. The XNA stuff just seems particularly
> poorly documented, like it's not really strategic or something.

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

The thing that annoys me about MS products is that if one day somebody 
phones you up and says "when I try to open Outlook it says error 28123", 
there is *no way* of discovering WTF this code actually means. If you 
open the settings for a program and some option has an ambiguous name, 
you can't look up what the setting actually does. [Bonus points for 
inventing the "help button" which informs you "no help is available for 
this item".] If I see something in Task Manager called mdm.exe, there is 
no way of finding out what this is, what it actually does, or anything 
about it. "Cryptographic Services". Cryptography *for what*? So, do I 
need this? Is it safe to turn it off? Or is it vital?

In short, almost nothing is documented. I find this extremely frustrating.

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

The Commodore 64 came with an extensive (yet surprisingly small) user 
manual which, as well as telling you how to wire up the device [which 
admittedly isn't that hard] and advertising all the addons you could buy 
[not many], also tells you everything there is to know about programming 
in BASIC. Well, except for the part about how to *design* a program. It 
tells you exactly what every single command and function in the language 
does. [Admittedly, there aren't that many to describe.]

The Sam Coupe had an excellent manual. Actually, it was excellent 
hardware. It's surprising that nobody's ever heard of it. If you imagine 
a C64 or a ZX Spectrum with a 6MHz CPU, 256KB RAM (upgradable to 4MB), 
128-colour graphics, stereo digital sound and an implementation of BASIC 
with primitives like drawing a curved line with one command, that's 
basically the Sam. The manual was extensive, assumed no prior experience 
with computers, and told you EVERYTHING.

Then again, back in the 1980s, how many home users had experience of 
computers?

Today, if you buy a new PC, you don't get a manual at all. Then again, 
it doesn't [usually] come with any software. Or if it does, it's just a 
copy of Windows. Windows sometimes has a small pamphlet to tell you how 
to work a mouse, and that's about it.

If you want to learn to program in Haskell... good luck. There's the 
official language specification - which is intended for compiler 
writers, and hence assumes that you already know the difference between 
the untyped lambda calculus and the simply-typed lambda calculus, and 
why the fixed-point operator cannot exist in the latter. (Interestingly, 
the language spec is linked from the Haskell homepage. WTF?) If that 
doesn't do it for you, there's maybe three books you could buy, or it's 
blogs and wiki pages.

The Haskell compiler, GHC, has a number of Haskell extensions that you 
can switch on. The documentation for these is... minimal. Most of them 
say "for more information see this [blog | wiki page | mailing list 
email | PDF research paper]".

Of course, GHC is a product given away for free. Presumably we should be 
grateful that the developers wrote any documentation at all. They are 
rather busy trying to sort out the 468 open tickets on the bug tracker. 
(I didn't pluck that number out of the air. As of 11:55 BST on 
15-Apr-2011, there are 468 open tickets.)

When you *buy* an expensive commercial product, you expect better than 
this. Sometimes you get it, sometimes you don't.

Post a reply to this message