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.
Part I: Getting Started with FileMaker 8
Using FileMaker Pro
Defining and Working with Fields
Working with Layouts
Part II: Developing Solutions with FileMaker
Relational Database Design
Working with Multiple Tables
Working with Relationships
Getting Started with Calculations
Getting Started with Scripting
Getting Started with Reporting
Part III: Developer Techniques
Developing for Multiuser Deployment
Advanced Interface Techniques
Advanced Calculation Techniques
Advanced Scripting Techniques
Advanced Portal Techniques
Debugging and Troubleshooting
Converting Systems from Previous Versions of FileMaker Pro
Part IV: Data Integration and Publishing
Importing Data into FileMaker Pro
Exporting Data from FileMaker
Instant Web Publishing
FileMaker and Web Services
Custom Web Publishing
Part V: Deploying a FileMaker Solution
Deploying and Extending FileMaker
FileMaker Server and Server Advanced
Documenting Your FileMaker Solutions