An Abstract View of Documentation

I've been thinking a little about the documentation of a system.

I think that there are two sorts:

• Descriptive
• Transformative

Descriptive documentation describes a system at a given state of time.

Transformative documentation describes the transformation of a system as a result of change.

Transformative documentation is only maintained for the duration of the change and is thereafter left as a record of the change. The work defined by transformative documentation results in change to the descriptive documentation.

Descriptive documentation is maintained for the lifetime of the system and is changed as the system is changed.

I think that by classifying documentation in this way one can start to define what documentation is required.

Ideally descriptive documentation should provide a clear, succinct and easily maintainable view of the system in question. Transformative documentation needs to clearly define the necessary changes and only be maintained to correct mistakes.