Channels ▼


Diary-Based Engineering

If you are the development team, you've probably found that many software methodologies don't apply. We had a very small support department, and only survived on the strength of our documentation. Detailed records of what happened were life-savers when a similar problem cropped up a year later. Here are some sure-fire tips for increasing productivity when developing software on your own.

One lesson that I drummed into successive operators was that searchable content is more important than formatting. I banned the use of the word processor and we used simple text files on the VAX. Later, we graduated to the online help system because it was still easily searchable, but added some structure. Plus, You can't afford to rely on your memory if you can't guarantee how long you'll be working on the same task. The smaller the team, the more likely that your current task will be interrupted for a significant break.

Diary-Based Software Engineering

The essence of this approach is a series of diaries. The various diaries have overlapping information but distinctly different purposes. This is like documenting a design with overlapping scenarios and techniques—the redundancy helps you avoid missing any important points and all it takes is a text editor and optionally, a second computer to avoid flipping your current work out of view while you record it. Giraffe-necked UNIX programmers with 21-inch monitors are excused.

The Site or Project Diary summarizes external factors that may affect the project and to track interaction with the client such as changes in the environment, including hardware and incidental software such as the operating systems or anything that can affect your project, a log of installations and a log of user bugs.

The Random Thought Diary tracks ideas without in-depth analysis to quickly capture ideas before they fade, such as new features, problems you may encounter and need to research, and alternative implementations.

The Design Decisions Diary captures the basis for a design decision, the supporting arguments and rejections that prevents you from wasting time reinventing "brilliant" ideas six months later.

The Code Change Diary tracks code changes in enough detail to let you recreate or undo them.

The techniques I've discussed could easily be combined into a software product. A cross-reference database would be nice, as would reminders linked to the Thoughts diary. However, this simple text-based approach is small enough to be used and powerful enough to be useful.

—Andy Dent, "Solo Engineering," Increasing Productivity (This story originally appeared in the April 1996 issue of Software Development magazine.)

Today, Diaries Revisited

Ten years of thinking out loud

Whilst a lot has changed in ten years, developers still need help to focus thinking. Feedback generally applauds it as a process small enough to be followed and still effective. Agile Development fits the diary-driven process nicely. Agile stories are natural topic headers for both diaries, providing briefing notes to get pairs up to speed

An ever-growing document seems a natural for version control but can be a distinct pain. A single document is a choke-point for locking VCS like SourceSafe. CVS-style merges report conflicts if changes only ever append content.

Individual diary files avoid VCS clashes and provide a coherent history, without distraction from flicking between writing styles. A single directory of multiple design diaries is not much harder to search than a single text file.

A major benefit of individual code-change diaries is providing a place to compose check-in comments whilst the work is done. A typical terse couple of lines composed at commit time is instead a paste of what has actually been changed, saving the casual browser from having to diff each source file and making commit notification emails more informative.

Code-change diaries with every change noted (horrors!) have been a harder sell in a team than the design diary. In four varied teams, I've found it best to lead by example. Even with management agreement and authority to dictate their use, a few months of seeing diaries accumulate in the project is more convincing, as individuals take their un-pressured time to adopt the practice.

For distributed teams, particularly open-source groups, IRC or mailing list debates summarize nicely to design diary lists of alternatives and the every-important why.

—Andy Dent

Related Reading

More Insights

Currently we allow the following HTML tags in comments:

Single tags

These tags can be used alone and don't need an ending tag.

<br> Defines a single line break

<hr> Defines a horizontal line

Matching tags

These require an ending tag - e.g. <i>italic text</i>

<a> Defines an anchor

<b> Defines bold text

<big> Defines big text

<blockquote> Defines a long quotation

<caption> Defines a table caption

<cite> Defines a citation

<code> Defines computer code text

<em> Defines emphasized text

<fieldset> Defines a border around elements in a form

<h1> This is heading 1

<h2> This is heading 2

<h3> This is heading 3

<h4> This is heading 4

<h5> This is heading 5

<h6> This is heading 6

<i> Defines italic text

<p> Defines a paragraph

<pre> Defines preformatted text

<q> Defines a short quotation

<samp> Defines sample computer code text

<small> Defines small text

<span> Defines a section in a document

<s> Defines strikethrough text

<strike> Defines strikethrough text

<strong> Defines strong text

<sub> Defines subscripted text

<sup> Defines superscripted text

<u> Defines underlined text

Dr. Dobb's encourages readers to engage in spirited, healthy debate, including taking us to task. However, Dr. Dobb's moderates all comments posted to our site, and reserves the right to modify or remove any content that it determines to be derogatory, offensive, inflammatory, vulgar, irrelevant/off-topic, racist or obvious marketing or spam. Dr. Dobb's further reserves the right to disable the profile of any commenter participating in said activities.

Disqus Tips To upload an avatar photo, first complete your Disqus profile. | View the list of supported HTML tags you can use to style comments. | Please read our commenting policy.