8. Data
The data associated with a software system is usually not the primary point of focus yet it’s arguably more important than the software itself, so often it’s useful to document something about it.
Intent
The purpose of the data section is to record anything that is important from a data perspective, answering the following types of questions:
- What does the data model look like?
- Where is data stored?
- Who owns the data?
- How much storage space is needed for the data? (e.g. especially if you’re dealing with “big data”)
- What are the archiving and back-up strategies?
- Are there any regulatory requirements for the long term archival of business data? - Likewise for log files and audit trails?
- Are flat files being used for storage? If so, what format is being used?
Structure
Keep it simple, with a short section for each element that you want to describe and include domain models or entity relationship diagrams if they help the reader. As with my advice for including class diagrams in the code section, keep any diagrams at a high level of abstraction rather than including every field and property. If people need this type of information, they can find it in the code or database (for example).
Motivation
The motivation for writing this section is that the data in most software systems tends to outlive the software. This section can help anybody that needs to maintain and support the data on an ongoing basis, plus anybody that needs to extract reports or undertake business intelligence activities on the data. This section can also serve as a starting point for when the software system is inevitably rewritten in the future.
Audience
The audience for this section is predominantly the technical people in the software develop- ment team along with others that may help deploy, support and operate the software system.
Required
No, but I usually include this section for anything other than a trivial software system.