It's standard practice for researchers to keep a detailed journal or log of their work. This allows procedures, methods, results, and conclusions to be scrutinised at a later date.

Software developers rarely practice this discipline. I've been in both camps: as a nonjournal keeper and a detailed journal keeper. I wholeheartedly recommend the practice of keeping a journal and encourage all developers on my projects to maintain and share detailed journal files.

What should go in your journal?

A journal doesn't have to be complicated. A plain-text file is best, so you can add it to your version control system and track changes.

Each day, append the date and start typing. Talk your way through problems and solutions. Write down your options, opinions, observations, test strategies, results, and decisions. If you take a wrong turn, note why things went astray and describe your alternatives. If you encounter a bug or problem, describe it and how you fixed it.

A journal is a diarylike personal account of your work, which means it doesn't replace formal project documentation or comments in the source code. Expect to write approximately a few hundred lines a day.

Finally, don't edit. Describe what you're about to do, and then detail the results. Keep it honest and include the good, the bad, and the ugly.

Should you share your journal with colleagues?

Yes--you and your colleagues should read each other's journals. Remember to check in your journal to the version control system at least once a day.

Glancing through journals takes little time, and you'll get a better understanding of how your project is fitting together and developing. If you see that a colleague is having a problem, you might be able to offer insight early on, rather than having it go unnoticed until the next status meeting.

You can also track the project's development through the journals without interrupting the team's work. You'll get real insights into the progress and see the bottlenecks and problems faster.

Remember that a journal is mainly for the benefit of the individual developer and not the project manager. So avoid the temptation to judge the content harshly or to dictate the style; otherwise, the journals might turn into fictionalised accounts that are useless.

What are the benefits?

Here are a few of the real benefits:

Improved focus and productivity: Most offices and labs have too many distractions; maintaining a journal helps you remain focused. You'll also be more likely to avoid reattempting old solutions, which you dismissed for reasons you might not remember. It might seem contradictory, but you'll find that your productivity increases as you spend time writing things down.

Better, quicker decisions: Describing an idea in a tangible form transforms it from being a passing thought into something clear and understandable. You'll find that you can choose and eliminate ideas more quickly by writing them down and describing your options. If you're a fan of Extreme Programming but can't practice Pair Programming (for practical reasons), then maintaining a detailed journal can be the next best thing to a real programming buddy.

Detailed history: Days, weeks, or months later, you'll be able to recall why you implemented a feature one way rather than another. Source code comments describe the end solution, but the journal describes every step you took to get there.

Better multitasking: It's difficult to switch between projects, but we have to do it. Reading back through your recent journal entries will help you get back on course quickly.

David Brenan is an independent embedded systems developer with more than 15 years of experience. His work includes the design of award-winning professional digital audio products.

	Download - White Papers! Security - Click Here To Read More Communications - Click Here To Read More Network Management - Click Here To Read More Software - Click Here To Read More