Bad example code is an opportunity, not a problem

Karl Seguin has recently vented his frustration at Microsoft's example code for their new Silverlight APIs. This is nothing new. I've developed with Microsoft technologies since the days of Windows 3.1 and the one constant feature of every technology that came out of Redmond was, and apparently still is, the poor quality of the example code. I used to have the same attitude as Karl. How could Microsoft release such crap and expect developers to learn how to use their stuff well?

But then I installed Resharper and realised the genius behind Microsoft's terrible example code. I found that I quickly learnt a lot about how the example code worked by refactoring it from the tangled web of confusing names and spaghetti logic into a well-structured design with a consistent, descriptive system of names. Obviously Microsoft understood the value of scratch refactoring years before refactoring tools were even invented.

Comic Life (and Work)

Chris Rimmer (on the right in the picture) presented an excellent comic-book style poster at XP Day to publicise the Oxtremists study group in Oxford.

That got me thinking... would a comic book be a good form for end-user documentation? It would be fun to write, would be good for showing graphical user interfaces and comic books have well known conventions for annotating pictures with to show movement and sound and direct the readers attention to detail.

I'm not the only one to think this. The developers of BJS, an open source game project, had the same idea and have already published their user manual as a comic book.

Update: Sun used the comic book form for the user documentation of their AnswerBook product way back in 1991.

Update:These graphic resources could be useful for writing comic-book documentation.

Update:Kevin Cheng has posted a list of resources for creating comic book content for design and end-user documentation.

Invasion of the Pod People

The other night I was at an alt.country gig where two DJs played tunes by linking their iPods into the PA system. Rather disappointing from my point of view: I'm an old fashioned kind of chap who thinks a DJ should follow tradition and spin vinyl. And a 7" 45 sounds better than an MP3. No, really, you get more top end from a 45.

Anyway, I digress. At some point a punter requested a song that the DJs hadn't brought with them. So he pulled his own iPod out of his pocket, plugged it into the system and played the song.

I have seen the future. The pod people are taking over!