(absolutely quite a bit, actually, say it again)

James at work said yesterday that often he finds, paradoxically, the code that is best documented is also the code that needs documentation the least, since it tends to be well designed and written in the first place.

I know what he meant, and it rang a little bell with me (although whether my code falls into that category is for others to judge :) ).

In lots of the places I’ve worked I’ve tended to be one of the few people who writes documentation, and I often wonder whether anyone else reads it. Is it, perhaps, all a monumental waste of time?

That said (and when I’m not having a bad day), I believe that to worry too much about whether it gets used would be to miss the fundamental point.

The reasons that I write documentation, in order of importance, are:

• to clarify what I’m trying to do
• to clarify why I’m trying to do it
• to offer up my design for peer review
• to explain my implementation choices
• to note avenues that I’ve tried and rejected, to avoid others doing the same
• to help other people use what I’ve done

If anything, the “why?” is even more important that the “what?”. Spend a bit of thought on that one, and the rest may turn out to be irrelevant.

In any case, having other people use the documentation as a reference comes pretty far down the list of priorities.

Which doesn’t mean that I don’t want people to do that (it would really help, frankly, if more people would RTFM!). It does mean though that I’m not going to lose too much sleep if I feel that I’m the only one reading what I write.

At the end of the day, writing documentation, for me, is an essential part of the process of writing software, especially when working with others. How can you code a system that you can’t describe in words or pictures?

Having other people read it is just a bonus.

Last night, with a bit of trepidation, I let my eee 901 hackintosh upgrade itself to MacOS 10.5.7. I’d been putting it off for fear that I might end up with a non-bootable machine (I could have recovered from it, but it would have been a pain).

As luck would have it, it mostly worked ok.

After reboot, the main problem that I had was that the monitor settings had reverted to 1024 x 768, causing the top & bottom of the screen to be cut off. Since the Mac menubar is at the top, this was a bit of a snag, but luckily I know the layout of everything pretty well, and I also had the advantage of Spotlight. Hitting Cmd-Space brings up the spotlight search box (in the right place, interestingly, even though the menubar was in the wrong place), and typing the name of an application allows you to launch it.

After a bit of experimenting, I ended up just re-installed the kexts from the EEE-Utilities package put together by Gregory Cohen. This seems to have sorted everything out.

As you may have noticed, I’ve got an eee901, which I’ve turned into a Hackintosh (I’ve installed OS X on it). I’ve previously mentioned that I found it a bit sluggish - but no more!

I finally got round to upgrading the default 16Gb SSD drive to a much faster 64Gb one made by Runcore. By hell does it make a difference! The machine feels substantially quicker, and I very rarely hit the spinning beach ball these days (which happened all the time, previously).

If you’ve got one of these machines, I’d seriously recommend upgrading the SSD, regardless of the operating system you’re using. If my experience is anything to go by, you won’t be dissapointed.

I’ve just updated the blurb a bit on this group: http://www.elegantchaos.com/uk-mac-dev

After the excellent NSConference, I’m hoping that we can get a few more members on the list, and encourage a few more folks along to our monthly meetings.

Another excellent day, with some good sessions (core animation looks cool), and a fun finale.

I must confess to being a little bit weary now, and glad to be sitting at home. Tim & Scotty and the others must be knackered - I hope they have the chance to get thoroughly rat-arsed tonight.