Why Is Documentation Important?

There are two general types of software documentation: user instructions and system documentation. User instructions generally assist people who need to use or administer an application. System documentation is a resource for developers who need to make functional changes to a system. This chapter focuses on techniques for creating system documentation for FileMaker-based projects and covers a wide range of ways in which a developer can make a solution easier and more systematic to understand. Documentation for us goes far beyond an external document explaining various functions of your system: Elements of documentation are interwoven throughout ones database from commenting to naming conventions.

Creating high-quality documentation is an important yet often neglected activity in the software development process. It can be tempting to think that FileMaker is in some regard self-documenting. The natural language support it provides in naming fields, tables, scripts, and so on goes a long way toward making a system comprehensible. Also, people often choose FileMaker as a rapid application development tool because they e in a hurry to deploy a system and don have time to budget for documentation. And finally, FileMaker systems often evolve organically. They get constantly added to and tweaked, and at no point can someone sit down, declare a system done, and produce documentation.

Nonetheless, its important to balance the temptation to just get started and the need for speedy development, with the need to create a readable, maintainable system that will still be comprehensible after the original developers have moved on.

The most important step in documenting a system lies in developing a consistent naming convention and in making liberal use of comments. This "document as you go" approach is extremely economical and actually assists in the development process itself, by requiring that developers stop and think through how a routine or process should work before starting to build it.

Good documentation starts at the beginning of a project. Its a rare developer who can go back through a system and add comments at the end of a project.