Putting the Finishing Touches on Your Documentation

In addition to the items described previously in this chapter, several other kinds of documentation may be useful to include in your system documentation package. Many of these items can be derived from the work that was done in the projects initial analysis and design phase. These documents can be printed or kept as electronic documents, such as PDF files.

The documentation elements we recommend collecting for a database project are listed here:

• Data Model A complete data model is essential for understanding how the database structure has been designed. An entity-relationship diagram (ERD) is one of the most popular data models. We recommend creating a layout within your database where a current ERD may be viewed. You can draw the ERD using FileMakers layout tools, or copy an image in from applications like Visio or OmniGraffle.

For additional discussion of creating and using an ERD, see Chapter 5, "Relational Database Design," p. 129.

• Documenting the Relationships Graph All the facts found on the Relationships Graph can be derived from the DDR report. However, the visual representation of the Relationships Graph provides an additional means for developers to gain insight into the system. The Relationships Graph can be printed or saved as a PDF file.
• User Interface Diagrams For a complex system or a system with many subsystems, the overall navigation and use of the system should be documented. Depending on the scope and complexity of the system, it may be appropriate to include flowcharts, storyboards, or other diagrams to indicate how users interact with the system and access its features.
• System Flowchart The system flowchart should document the overall structure of the entire system. It should show how the various parts of the system interconnect and relate to each other. The system flowchart should also show manual processes and external systems or agents that the FileMaker system depends on.
• Process Descriptions Complex processes should be deconstructed and documented thoroughly with written descriptions. Decision trees, charts, and tables can provide additional details.
• Screens and Reports A complete set of documentation often includes copies of all screens and reports used in the system. In some cases it may be helpful to produce two sets: one created with sample data in Browse mode and another created in Layout mode with field names.
• Test Data Representative test data that shows both typical and extreme values can be a great asset in your documentation. Test data is especially helpful to those who are not familiar with the system. The test data can help eliminate assumptions about expected data and prevent misunderstandings between clients and developers.