On a related note, has anyone ever read a good book on microsoft programming techNologies (VB6, .NET, MFC, etc)? I don’t mean to single out MS developers/writers (I am one by day) but they seem to be the orst offenders in this regard.
It seems like everyone of these books (and the vast majority of msdn documentation) boils down to a click here, type this, click there, select this walkthrough.
If I’m reading documentation I want an explanation of the concepts and key parts involved (with links to reference documentation), not a step by step guide.
The same goes for tutorials. In a tutorial there needs to be some hand holding, but it should also take breaks at appropriate points to explain the concepts it’s dealing with.
I think the reason most people don’t document code is that they don’t know how to make it usefull.