Software Publishing: THE "D" WORD - DOCUMENTATION

From Dwayne Wright - Certified FileMaker 9 Developer
WEB: www.dwaynewright.com
EMAIL: info@dwaynewright.com
TWITTER: dwaynewright

This is part of my ongoing series of articles about setting up your own software publishing business (cause FileMaker is very good option for doing that). This was originally published by me in a guide called FileMaker Software Publishing back in 2002. .

THE "D" WORD - DOCUMENTATION
I’ve seen the question "Where is the documentation on this solution" cause fear, pain, bewilderment and even anger arise out of a FileMaker developer. Solution documentation is broken down into 2 main categories, which are developer documentation and user documentation. We will discuss the user documentation later on. For now, we are going to discuss the designer level documentation of FileMaker design elements.

Design documentation in a FileMaker solution isn’t very easy. FileMaker itself does not provide much capability in this area. So it’s hard to preach to you how necessary it is to do it when FileMaker Inc. seems to undervalue ( at least at the time of this writing ) design documentation's importance.

In a perfect world, you will be able to add comments, to search by comments and organize by comments the following FileMaker objects…

- Scripts ( available to a limited degree )
- Script Steps
- Fields ( available to a limited degree )
- Calculations ( available to a limited degree )
- Relationships ( available to a limited degree )
- Relationship keys
- Layouts
- Objects On A Layout
- Value Lists

Scripting documentation with a scripts is available by a comment script step. This is OK when you want to document what a particular set of script steps are going to do within the overall flow of the script. Fields allow you to add a brief comment about the field right below the field name. Calculations allow you to mark a string of text within the calculation as a comment. Relationships allow you to create a very limited sticky note about some area of the relationship graph. All of these options are welcomed but they do fall squarely into the category of “better than a poke in the eye with a sharp stick”.

Here you can see the comment area for a particular field.

Much like Rodney Dangerfield, why does design documentation get no respect? First off, documentation of design doesn’t have significant marketing sizzle. Can you imagine the excitement of a new version of FileMaker that costs $100 more primarily for designer documentation functionality? It’s much like telling a consulting client they will pay an additional $10,000 for design documentation. However, if you tell the client that the documentation will save them productivity dollars in the future, they may consider it a reasonable return on their investment.

You can cut the task significantly if you design, document and adhere to a standard for database design. By creating a defined set of naming your elements, you can embed some of your documentation in the name! If you think this is enough, you will come up short. Anyone that thinks there design is so clean that it doesn’t need documentation is dangerous. The best way to be safe is by documenting everything you possibly can.

Here are some links to other posts that might be of interest in regards to this topic...
Calculations No Longer Say “No Comment”
Adding Comments To A Script
Formatting In Script Comments
=
More info about the author and FileMaker in general, contact me at info@dwaynewright.com.

© 2008 - Dwayne Wright - dwaynewright.com

The material on this document is offered AS IS. There is NO REPRESENTATION OR WARRANTY, expressed or implied, nor does any other contributor to this document. WARRANTIES OF MERCHANT ABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE EXPRESSLY DISCLAIMED. Consequential and incidental damages are expressly excluded. FileMaker Pro is the registered trademark of FileMaker Inc.
====================== ADVERTISEMENT ==============================
Check out the FileMaker Term Of The Day at http://filemakerterm.blogspot.com/ or subscribe via your news reader. ===================================================================