DW4H (Documentation – why, when, what, who, how)

DW4H (Documentation – why, when, what, who, how)

I was asked recently to explain how the development process deals with documentation.

The question that needs to be answered is "Why?" — why is documentation needed, by whom, for what purpose? In my view, there are two purposes for documentation, and they are radically different from each other.

The first purpose is to describe what is going to be done in the future. This future-facing documentation — in the form of traditional project mission, value forecasts, customer requirements, technical architecture and design specifications — is produced before a product is built. It defines the work that will be done.

The second purpose is to describe what has been done in the past. This historical documentation — usually the updated design and implementation documents — is produced as the product is being built, or after the product has been built and deployed. It defines the work that was actually done.

As you see, the timing of the documentation strongly influences what is produced, when it is produced, who produces it and how it is used. It also influences the value of the documentation.

Future-facing documents generally form constraints on the planned work. The intent is to focus the effort on the desired outcome. Because it is future-facing, it is necessarily uncertain and subject to change as the future comes closer.

Because the future is uncertain, future-facing documentation should be expressed with the same degree of uncertainty. As we plan a project, we can be highly certain about some subjects — project mission, customer goals, architectural principles and system models — and far less certain about other subjects — value forecasts, customer requirements, functional capabilities, technical architecture, design specifications. The future-facing documentation should reflect that.

Likewise, future-facing documentation must be easily changed, as the effort progresses and we become smarter and more certain about what we are building and how we are building it. Documentation should always be current (to avoid confusion) and never be a burden. Burdensome documentation becomes obsolete. Obsolete documentation becomes ignored.

Historical documents generally form descriptions of the executed work. The intent is to help some unknown future persons who may need to know how the products were designed, how they were built,  and how they behave. Because it is historical, it can be as certain and free from change as past events and real products are. (This doesn’t keep them from being incomplete or wrong, of course.)

Historical documents should be expressed with a high degree of certainty. All the uncertainty that we faced at the start of the project should be removed at the end of the project. Historical documents describe the customer requirements that were actually met, the technology that was actually deployed, the design that was actually implemented, and the capabilities that are actually supported. While historical documents are still subject to change, the change is typically less frequent and less urgent than it is with future-facing documents.

Continue reading

Identity Exposure is an Architecture Failure

Today’s software story is on the front page of the day’s news: 

Monday, May 22, 2006; Posted: 5:46 p.m. EDT (21:46 GMT)

WASHINGTON (CNN) — Personal information on 26.5 million veterans was stolen from the home of a data analyst in what appears to have been a random burglary, Veterans Affairs Secretary Jim Nicholson said Monday.

The computer records include names, Social Security numbers and dates of birth, Nicholson said. The Department of Veterans Affairs disclosed the theft Monday and said it has seen no indication that the information has been misused.

The analyst took the data home without authorization, Nicholson said. Department spokesman Matt Burns said the employee has been put on administrative leave while the investigation is conducted.

What makes this a story about software? Exactly this: Why did the software architecture permit this personal data to be available to anyone in the VA?

Continue reading