Work Log

A work log records attempts, observations, and decisions as work proceeds. A simple table is a useful starting point, with columns such as the attempt, the observed result, and the decision, including why an option was kept or rejected. Add enough detail to understand what was tested, and record the accepted rule’s assumptions and test evidence as well as failed attempts.

Rejected attempts help avoid repeating work, but do not prove the remaining choice correct. Suppose a trip’s duration must be computed from start and end clock times alone, and you adopt the rule “take the difference modulo one day” so that a trip crossing midnight comes out positive. That rule is right only if every trip lasts under 24 hours and the clock never shifts, for example through a time-zone or daylight-saving change. Record the failed alternatives together with the evidence for those two assumptions. If the evidence is missing, mark the rule as conditional rather than validated for every trip.

Record the things that are expensive to recover: the exact error text, the input that triggered it, the versions in play, the source of any rule you adopted, and the decisions you made about ambiguous cases. Avoid recording what the code already says. Anything a reader would otherwise have to reconstruct by rerunning the work belongs in the log; anything they can read in one line of source does not.

Move lasting decisions into code comments, tests, and change records so they remain available with the implementation. A human work log explains reasoning and decisions; program logging records runtime events and can supply supporting evidence, but does not replace that explanation. Keep credentials and personal data out of shared records.

See it in use in Researching Errors and Organizing Analytical Work.

References:

• Python logging
• how to create a minimal reproducible example