| To my way of thinking documenting the work is vitally important, even more important than planning in some respects. Or maybe we could say planning is just another form of documenting what we're doing (or trying to do). Sure, writing code is the stimulating creative part. And purifying code, making it elegant, polishing the creation to a brilliant sheen is highly rewarding. By contrast, documenting what's been done is tedious, boring, a gigantic pain, a total drag. Yet if it's not adequately documented all that creative effort will inevitably amount to nothing but a reason to hate its creator. Furthermore, is it really possible to write superb documentation for lousy code? The effort to document the work is a kind of quality check on the work. Can't say how many times it's come back to bite me where it hurts. Looking at stuff I finished 6 months, or God forbid, 6 years ago, poorly documented programs invariably prompt a shameful recognition that I have no idea what the hell I did. At least when someone else wrote it I can justify feeling indignant at the "mess" I have to figure out. But when it's my own, that's just sad. Of course the work we leave behind (at the end of a job, retirement, etc.) will usually be resumed by someone. Excellent documentation is our finest legacy. Consider how it supports moving a project forward when the code's author isn't there to "explain" how it works. And if we're honest with ourselves, writing cogent documentation is hard, often much harder than writing code which is why it's such a brutal task. OTOH doing something hard is a good reason to tell oneself "A big accomplishment! Good for me!" Something to feel good about! A rule I aim to live by: the workday isn't over until I record what I just did and the reasons for doing it the way it was done. |