Why Is Documentation Important?

There are two general types of software documentation: user documentation and system documentation . User documentation is a resource to assist people who need to use or administer a system. System documentation is a resource for developers who need to make functional changes to a system. This appendix focuses on techniques for creating system documentation for FileMaker-based projects.

Creating high-quality documentation is an important yet often neglected activity in the software development process. Because FileMaker is such an intuitive tool, it is easy for developers to put off the documentation process. But sometimes a system that began as a simple contact management tool grows into a monster system with hundreds of layouts and thousands of fields and scripts. When the time comes to modify a feature that you haven't looked at in months or even years , documentation will be your best friend.

It can be tempting to delay documentation preparation until a system is complete. But in many projects there simply isn't time (or money, if the project has a specific budget) left when the project is finished to create documentation, and your memory of the system details at that point can also become fuzzy. So because it's often too late to initiate documentation at the end of the project, it is important that you adapt your workflow to include practices that contribute to creating good documentation as you work. The most important of these are developing consistent naming conventions and making liberal use of comments. We'll discuss both of these practices further in the course of this appendix, but one constant consideration is to make sure to budget a little extra time to create and maintain your documentation as you go.

One of the points we'll make here more than once is that good documentation begins at the beginning of a project. Some of these techniques become more difficult to put into place in a system that's already built.