Sun's Documentation

Last updated: Tue, 08 Feb 2005 11:02:00 GMT

It sucks.

Don't get me wrong; their man(1) pages are acceptable. I prefer reading Sun man pages to wading through the swamp of ${TEH_L33TEST_LINUX} man or info pages. But beyond that their documentation is useless. Until five minutes ago I thought it was just me, and then I got chatting to a colleague.

He was complaining about RAID Manager. Not the first time we've bitched about this particular product, but this time it wasn't about its spectacularly obtuse location, or its endearing habit of mailing root all the time to say "Everything's cool." This time it was about the documentation. It seems that this was the first time he'd had to read a Sun manual in anger.

"Don't get me started," I said, "it's like a read your own bloody adventure -- Steve Jackson lives!"

"That's exactly what came to my mind," he smiled.

For some reason Sun think that the best way to write documentation about anything is to break it down into step-by-step instructions. But, because a lot of life can't be boiled down to a straight line from point A to point B, step-by-step doesn't work -- we need conditional branches, loops, and so on.

And so we end up with a manual that takes twice as long to read and, this is the killer, contains no useful information. We spend all of our time flipping back and forth, rolling dice and killing trolls, and at the end of the day we've learned nothing about what it is we want to do.

These manuals suffer from the same problem as those read your own adventure books of yore: they're still linear. Yes, you get to make a decision here and there, but your choices are constrained by the author's imagination. What if I don't want to exit north or west? What if I want to stop, wash my feet in this stream and ask myself what exactly I'm going to say to this princess when I reach the top of the tower?

Word to the wise, Sun: if the people you're writing for can't be educated and then trusted to make their own decisions, maybe those people should be kept away from the # prompt.

I'm sure that not all of their documentation is crap. Both my colleague and I suggested that the "Basics of Using the boot Command" document (ID: 48569, go and search Sun's fantastic web site) was notably useful and well written.

On revisiting it (I have it on paper, which is telling,) I have to agree that it is useful and easy to read. It takes a descriptive tack, rather than prescriptive. But it's little more than a man page, so I figure I'm still searching for a Sun manual that doesn't suck.

[A friend points out that I may be being a little inclusive in damning all of Sun's manuals. Apparently their java documentation is useful and usable.]