Computer programmers include commentary in their computer code, reminders for themselves when they read it later, and notes for other programmers who might read the code someday. There's a common rule-of-thumb surrounding this discipline that says you should document the “why” rather than the “what”. Instead of “this code updates the latest prices on the auction site”, say “we update the prices here because it has to happen instantly once a new bid has been submitted”.
I think there's a lesson to be learned when explaining things in all disciplines of life. In this age of constant connectivity, the “what” is trivial to look up, but still very few sources can adequately enumerate the “why”.
- Drug A stopped being the preferred treatment in 2004…but why?
- Movie Director J. Smith hasn't release a new film in 6 years…but why?
- LCD Television Sales are dramatically out-pacing Plasma TV sales…but why?
Toddlers are renowned for annoyingly tittering “why? why? why?". Maybe they are onto something.
Thought Partner: Software Engineering Radio