September 2006

It would seem obvious to blame the recent Thai coup for why I didn't manage to get any of the Subversion pieces I'd promised published this month, but it wouldn't be entirely accurate.

Tanks on the streets of Bangkok.It is true that I pushed up some (meta?) writing on Thailand and I did spend a fair bit of time publishing a set of photos that I otherwise might have spent working on writing the Subversion pieces, but actually I've been wasting my time playing Egosoft's X²: The Threat and X³: Reunion. I have no other real excuse. Sorry.

Writing quality and accuracy

I think like many others I'm often dismayed by the quality of the writing that I come across on the Internet. In How not to teach database design I try to give some tips on how to be clearer when writing. The most important aspect is to think through how the information you are trying to convey will be perceived by your audience. What I didn't particularly dwell on though was accuracy.

One of the reasons I spend so long writing articles (just look at the difference between the created and last updated timestamps at the top of most of them) is that I want to make sure that not only is what I am trying to convey clear, but it is also correct. If I do make mistakes (and we all do) then my policy is not to silently correct an error and pretend that I'm infallible, but to correct it and footnote why I made the mistake. Hopefully this will get me to better check my facts next time.

Just after I published How not to teach database design I came across Programming an HTML Downloader in C++ by Alwyn Malachi Berkeley on Scratch Projects. This article is fairly well written and is certainly engaging. The trouble is that the quality of the code is appalling.

I can't help but think that accuracy is probably more important than even clarity when writing about technical subjects. If the advice is wrong and there is no way to correct it then what should be done? What does the existence of this tutorial on Scratch Projects tell us about the rest of the site's content (which I have not reviewed)?

So far I have contacted Alwyn about the problems in the code but not Scratch Projects. I suppose that I ought to contact them too, but was hoping to hear from Alwyn first (so far I've heard nothing).

I'm also trying to work out what I should do in the future. Is it right of me to name and shame? Clearly I've done so in this case, but I'm sure that there are many other examples of these sorts of inaccuracies elsewhere. I neither have the time nor the inclination to go and search for them all and this is possibly a little unfair on Alwyn as he's been singled out.

Alwyn is a young programmer and clearly not very experienced yet. That he has bugs in code that he's published to my mind is not an unforgivable error, but not correcting it will be. I shall wait and see how he deals with the issue. As for myself I guess I will continue to be crotchety about blatant errors — that's all part and parcel of turning into an old(er) man I suppose (I had my 36th birthday this month).