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.