Channels ▼

What's Normal? Models to Documentation

Software Development's Agile Modeling Newsletter: December 2004

In Agile Modeling (AM), you want to travel as light as possible, so you need to choose the best artifact to record information. (I use the term "artifact" to refer to any model, document, source code, plan or other item created during a software development project.) Furthermore, you want to record information as few times as possible; ideally only once. For example, if you describe a business rule in a use case, then describe it in detail in a business rule specification, then implement it in code, you have three versions of the same business rule to maintain. It would be far better to record the business rule once, ideally as human-readable but implementable code, and then reference it from any other artifact as appropriate.

Why do you want to record a concept once? First, the more representations that you maintain, the greater the maintenance burden, because you'll want to keep each version in sync. Second, you'll have greater traceability needs with multiple copies because you'll have to relate each version to its alternate representations to keep them synchronized when a change does occur. AM does advise you to update only when it hurts, but having multiple copies of something means you're likely to feel the pain earlier and more often. Finally, the more copies you have, the greater the chance you'll end up with inconsistent information, as you probably won't be able to keep the versions synchronized.

It's interesting that traditional processes typically promote multiple recordings of technical information, such as representing business rules three different ways, while also prescribing design concepts such as normalization and cohesion that promote developing designs that implement concepts once. For example, the rules of data normalization motivate you to store data in one place and one place only. Similarly, in object-oriented and component-based design, you want to build cohesive items (components, classes, methods and so on) that fulfill only one goal. If this is O.K. for your system design, shouldn't it also be O.K. for your software development artifacts? We clearly need to rethink our approach.

It's clear that you should store system information in one place and one place only, ideally in the most effective place. In software development, this concept is called "artifact normalization"; in the technical documentation world, it's called "single sourcing". With single sourcing, you aim to record technical information only once and then generate various documentation views as needed from that information. A business rule, for example, would be recorded using some sort of business-rule definition language. A human-readable view would be generated for your requirements documentation (easier said than done, but for the sake of argument, let's assume it's possible) and an implementation view generated that would be run by your business rule engine or compiled as application source code.

To make the single-sourcing vision work, you need a common way to record information. Darwin Information Typing Architecture (DITA) is an XML-based format that's promoted for single-sourced technical documentation. Nothing can stop you from creating your own storage strategy: Single sourcing is often approached in a top-down manner with the data structure for the documentation typically defined early in a project. However, you can take a more agile approach in which the structure emerges over time.

The primary challenge with traditional single sourcing? It requires a fairly sophisticated approach to technical documentation. This is perfectly fine, but unfortunately, many organizations aren't yet able to achieve this vision and eventually back away from the approach. This doesn't mean that you need to throw out the baby with the bath water; you should still strive to normalize all of your software development artifacts.

Just as it's extremely rare to find a perfectly normalized relational database, I suspect that you'll never truly be able to fully normalize all of your software artifacts. In the case of databases, performance considerations (and to be fair, design mistakes made by project teams) result in less-than-normal schemas. Similarly, everyone won't be able to work with all types of artifacts -- it isn't realistic to expect business stakeholders to be able to read program source code and the ¼ber-tools required to support this vision continue to elude us. However, we can still choose to travel as light as possible, and next month, I'll describe techniques for doing exactly that.

-- Scott W. Ambler


What Does It Mean to Be Agile?
To get some input for my January 2005 print column ("The Agility Quotient"), I asked this question to the list members. We debated a wide range of concepts, such as being feedback- and change-friendly, willing to work in a collaborative manner, willing to focus on delivering working software that meets the needs of its stakeholders, willingness to work with stakeholders, and flexibility in your approach. Keep an eye out for my column, which describes these ideas in detail and suggests a tongue-in-cheek rating system.

Cost of Change Curve
We discussed the merits of the agile cost of change curve, which in practice proves to be much flatter than the traditional cost of change curve due mostly to the increase feedback prevalent in agile approaches. New metrics showing this to be true, and new techniques to support a flatter cost of change curve, are actively being worked on within the agile community.

Crystal Clear
I announced that Alistair Cockburn's latest book, Crystal Clear: A Human-Powered Methodology for Small Teams, was released by Addison-Wesley in late October. I've been waiting for this book for a long time and am delighted to finally see it in print. Crystal is summarized by seven properties: frequent delivery, reflective improvement, osmotic communication, personal safety, focus, easy access to expert users, and a technical environment with automated tests, configuration management and frequent integration.


JoAnn Hackos and Ann Rockley's article "Single Sourcing White Paper" overviews the fundamentals of single sourcing.

Pamela Kostur and Anne Rockley's paper "Information Modeling for Single Sourcing" describes a top-down process for single sourcing.

The Darwin Information Typing Architecture (DITA) describes a potential approach for storing normalized documentation in XML format.

The essay "Data Modeling 101" covers, among other things, how to normalize a database design.

Eliminating the Cost of Change essay explores the agile cost of change curve and explains why it works.

Links to critical MDA resources on the Web can be found at

The concept of generalizing specialists is described in detail at

Alistair Cockburn's latest book, Crystal Clear: A Human-Powered Methodology for Small Teams (Addison-Wesley, 2004), is worth a read.

The Agile Alliance homepage is the best starting point for anyone interested in learning more about agile software development.

The principles of Agile Modeling are described at

The practices of Agile Modeling are described at

Check out the Agile Modeling mailing list at

Get agile modeling training resources at

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.