Documenting your applications

Application documentation provides a more detailed record of what was done and why. Months or years later, you will appreciate such notes when you revisit the code to make modifications. And it is certainly a professional courtesy to other developers to provide insight about why some aspect of an application works the way it does.

There may be an organizational requirement to document applications in a certain way, and if so, do so. Consider going beyond the minimum requirements. In any case, leave tracks.

Add comments to the code

If you took a programming class somewhere along the way, you were told to add comments to your code. This admonition is still valid today. Comment complex or obscure code in a plain way so that future developers can more readily grasp the associated technical implementation.

Every agent should include a summary of what it does, how it is called, what calls it makes, and how and when it was revised. A complex @ formula or JavaScript function should likewise include statements describing what it does. Sometimes hidden text placed on forms also can be helpful.

Create internal developer notes

Developers generally write too little documentation, and what is written is often found in documents external to the Notes application itself. Months or years later, no one can find the external documentation. A new developer begins discovery of the application all over again.

Instead of writing external documents, use the Page design element to record developer documentation. Maintain a consistent naming scheme, and identify them as 'Developer Notes' in the Comment field on the Page Info tab of Page Properties. Keep these pages within the design template. They will take little space, and they will always be there for the next developer.

Add release notes to the About document

In addition to the application owner and developer contact information, an application's About document often includes release notes. Details about a specific release can be included in a separate collapsible section that lists changed elements.

Consider organizing release notes in an outline form. Here is a sample:

• Summary of Changes

• Developer(s)

• Database as a whole

• Framesets

• Pages

• Forms, and so on

Add numbered or bulleted items in each section with specific information about the changed design elements.

Include external documentation in the design as file resources

Word processing documents, spreadsheets, presentations, and so on created during the course of a project can be imported into the design template as file resources. In this way, relevant external documents are never lost and remain with the design for future reference.

Create user-oriented help pages

Application discovery is a great time to make notes about how an application works. If little or no useful user-oriented documentation exists, consider saving notes and screenshots on pages in a separate user help database. Work out a simple, common navigational menu for each page. Once the collection of pages is complete, deploy it for customer use as well as your own.