Keeping a log book

Andrew discusses the use of a ‘laboratory’ style notebook for software development. His suggestions are excellent, but should really be taken further, especially for junior developers.

A developers log book should record a variety of information

1. Designs, analysis and problem investigations as discussed in the
   previous post
2. All work and development related telephone calls, conversations and meetings
3. Debug sessions: Helps keep track of what is currently happening and also to help re-create the session later if required
   1. Settings, break points used etc. (the details required depends on the features of your tool)
   2. Results
4. Configuration settings for tools and other software you use plus notes about any changes (the reason why and the result of the change)
5. Time logging. At a minimum time arrived and departed plus blocks of time spent on each project. Don’t forget to add in time answering questions, going to meetings etc.
6. Useful pieces for information such as names, telephone numbers, documentation references and other snippets
7. Notes of builds and test runs including when, which tests and builds, and the result
8. References to ticket numbers that are being worked on
9. Summary of Revision Control Activity e.g.
   • Times of commits, updates (to use Subversion jargon) and merges to the version control system and relevant revision numbers (if using a system such as Subversion that supports a global revision number)
   • Note of any tags,branches or baselines you create

What form should the log book take? That depends on what works for the individual and the team. For example

• A paper journal, such as a Moleskine
• A more traditional planner such as a Filofax
• An ordinary loose leaf office binder
• A desk diary
• An electronic notebook such as Jarnal or OneNote
• An online repository, for instance a WiKi (Some WiKi software such as wikiPad support a local mode of operation)

Don’t forget include dates and if relevant put the name of the client as well.

So what is the point of all this record keeping?

• Communication: Answer questions promptly and accurately, even years after the event
• Efficiency: Don’t need to clutter up the mind with unnecessary information and make it easier to fill out your time sheet
• Historical record keeping: (a.k.a CYOA) Justify your decisions and progress with accurate data
• Task management and planning: Understand your commitments and plans to make sure you only promise what you can deliver. Stay on top of your workload. The lab book can be used in conjunction with task management systems such as GSD. Consider using historical data to make estimates. 
• Not forgetting things at 3:00am during an all night bug squash

Such records can also be useful for patent filling if that is something you need to do later. However record keeping to support patent applications is a whole subject on its own.

Updated 2/June/2008: There are some additional notes on 43Folders
Updated 11/Oct/2008: The Power of Writing Things Down

powered by performancing firefox