Day: February 6, 2003

It looks like we have a conversation going here.  Here’s Ingo’s latest:

Break the cycle. Write your next documentation the same way – and with the same quality – as if you’d write an article or book. Your readers will love it. And don’t forget: documentation is marketing your code to a peer.

I will definately do this the next time that I put together documentation.  In the past, I have found that good documentation or a good example of usage brings a smile to my face.

I’m not in the same corporate/professional situation as Ingo and others, where documentation is just a check mark next to a step in The Process.  I am definately guilty of putting together ‘good enough’ documentation just before a release or before showing someone my code.

I will follow Ingo’s advice and suggest that others do also.  I think that the open source community in particular should pay attention.  Sometimes the documentation is good, but more often than not it’s missing, incomplete, or poorly written.

If these notes on documentation don’t apply to you, if you already write good docs, thank you.

Ingo on documentation:

Technical writing is a form of communication which takes a certain degree of sophistication. Especially when you actually expect someone to read it.

Good technical documentation is hard to produce.  By the same token, good technical documentation is hard to come by.

While I was installing and rebooting and updating and rebooting this evening, I popped in a VHS tape makred “MTV.” It turns out that the tape is about half of the top 100 videos of 1995 (100-50ish). It was great to see some old videos and hear some old songs. It made me remember the days of flannel and long hair.

1995 was the year that I saw David Bowie and Nine Inch Nails from the mosh pit. I was in a band. At our first practice, we tried horribly to cover Soul Asylum’s Misery.

What struck me most wasn’t the videos, it was the commercials. The commercials told more about 1995 than anything else on that tape. Sure it was a big year for REM, Hole, Collective Soul and Hootie and the Blowfish. The thing that intrigued me most is that the Sega Saturn was being advertized for “Just $299.” I saw a few ads for Super Nintendo games. That annoying ad for the overpriced retro store down the street (which closed down several years ago) played a few times.

Today we’re so quick to skip the commercials, TiVO that stuff right out of our viewing experience. I think that if you still have a functioning TiVO eight years from now, you won’t skip the commercials when you watch that old show.

They’re a wonderful snapshot of who we are.

Scott Hanselman: “A reminder from Sairama that editing the DefaultWsdlHelpGenerator.aspx page in CONFIG underneath the .NET Framework directory allows you to customize the Web Services test page. Even if only to change the default textbox to a textarea, it’s a useful tip.”