Click here to learn more about author Michael Blaha.

Once you’ve created a data model, how do you document it? You need to deliver the model’s content to others – to business sponsors, other developers, and posterity for purposes that you may not envision. This article looks at options for documenting data models and their trade-offs.

Transmit the Model File

An obvious approach is to simply provide the file for the data modeling tool.

• Advantages. This approach is easy for the data modeler. You just hand over your model file.
• Disadvantages. The recipients must deal with a modeling tool. Some tools such as Vertabelo, are easy to operate; you merely type in email addresses to share online data models. Other more complex tools, such as ERwin and ER/Studio, have read-only viewers to simplify model access.
  A more serious drawback is that a large model can be overwhelming. Where should a person start? In a model, all constructs have the same weight and it’s difficult to call attention to the most important aspects. Furthermore, it’s difficult to convey rationale for why a model is constructed a certain way.
  The cost of modeling tools for multiple persons can also be a concern.

Print the Model

Another obvious approach is to printout a model, such as with PDF or HTML. You can augment a printout with a data dictionary that shows details, such as definitions, data types, and nullability, for entity types, relationship types, and attributes. Most data modeling tools can readily generate printouts and data dictionary reports.

• Advantages. Once again, this approach is easy for the data modeler. Also it’s simple to receive and requires no modeling tool skill. There is no tool cost and tool access.
• Disadvantages. However, printouts can be difficult to manipulate on a screen and unwieldy on paper. You may require a special printer with large paper for a model to be readable.
  And once again, there is no prioritization of a model. Everything is presented as equal weight and the reader is on their own.

Write a Narrative

The last approach is to write a model narrative. For example, you can copy and paste model diagrams into a MS-Word document and then write prose to explain them.
You can include full diagrams or model abridgements. For example, you may show full entity types, relationship types, and attributes. Or you may limit a diagram to the most important attributes. Or you may elide minor entity types and focus on the core of a model. Tools can perform some of these abridgements. Others you have to construct manually.
If you abridge a model, you might also include a data dictionary. You can also augment a data model with complimentary representations such as a data warehouse bus matrix.

• Advantages. This approach is convenient for others. A narrative guides the reader through the model and explains subtle decisions. There is no tool cost and tool access.
• Disadvantages. A narrative adds work for the data modeler. Furthermore, it’s difficult to keep a narrative current, as a model changes. If you use a narrative, you should timestamp the document to help the reader determine whether the narrative is up to date.

In Conclusion

All three approaches are viable options and have their trade-offs. We use all three techniques in practice. The choice depends on the audience and the complexity of the data model. This is consistent with our general approach to software development. We believe that developers should be fluent with multiple techniques and adapt to meet business needs.