Creating Documentation

[clz]

I am looking for advise/suggestions on the documentation that should be created for a project. I have never developed a database before, have no formal training and was just thrown into this project a few months ago. It, like many projects, began as just a small project to track some general information. It has now grown to over 15 tables with over 500 fields. Before it get's even larger, I want to document what I have already worked on. Does anyone has any suggestions on how to tackle this, format it, how much detail should be documented, etc.?

As a side note, most of my computer experience has been as a network administrator/engineer. Because this is a new, small company I am also working on this database. This is my first experience with FileMaker Pro and I must say it has been fun and challenging! I am amazed at what can be done with this program and am still learning something new every day. The only problem with that is I continually want to go back and rework what I have already done and I still have quite a list of new things to work on! This website has been a wonderful resource. I can't believe how much I have learned just visiting this site!

Cindy

[Ocean West]

Start by making comments in your scripts as developer notes. You will thank your self months down the road when you open a script you haven't modified in a while. You will see exactly what you were thinking when you developed. Also this is useful for multi-developer support.

Print out screen shots and jot down general notes this will help you collect your thoughts. You also need to consider your user whom is going to read this documentation, is this a "technical document" or is it a guide for beginners.

When creating "For beginners" document I would recommend you find yourself a beginner sit them down and you watch them use the system you give them pointers as to where to go and write down their actions. You will be surprised they may do things that you didn't intend. Also this will give you feedback for future revisions. Once you've written a guide. Find another beginner and have them follow the instructions as per the documentation and see if they can produce the intended results.

For technical documentation such as ER diagrams and the like this may take some more thinking and diligence in remembering to write down things you are doing. For example I had a database with a filed called "Mode" and the field could be 1 - 10 months there were many other scripts and fields that used the value of this field but months later I couldn't tell you what a Mode 3 was. Write it DOWN! As soon as you get the idea. Perhaps put a digital recorder next to you. Or create a "notes" database for you to jot down or voice record notes. Sometimes I launch BBEdit for making notes. Then compile all the notes into documentation.

Hope this helps..

stephen

[danjacoby]

Q: How many software developers does it take to change a light bulb?

A: 107. One to change it, and 106 to write the documentation.

[Anatoli]

In case of Apple light bulb it will be 117.

Team of 10 to develop replacement, one to change it, and 106 to write the documentation. "Not developed here" is hunting Apple for decades.

[SteveB]

And, unfortunately for us, none to figure out how to get the light to turn on, or replace the bulb when it burns out.

[danjacoby]

The good thing about writing the documentation (yup, there's something good about it!) is that you can utilize the opportunity to test every little facet of your solution. I've found a lot of tiny little buglets and other mildly (and sometimes not so mildly) annoying things about my solutions when writing a "Help" file.

Granted, when the solution is complex, the documentation is a bear, but it's often well worth it.

[SteveB]

One of the documentation tools that I've found helpful is a flowcharting tool. I use SmartDraw which is very inexpensive and extremely easy to use. You don't even need to read the help documentation...just unpack it and go. To be able to visually see program flow was very helpful. You can download a copy from www.smartdraw.com.

[clz]

Thanks for the great advise. I have a trial copy of Smart Draw and bought a copy of Database Design for Mere Mortals. I am reviewing what I have done so far and starting to create documentation for it. It's been an interesting process. I have done some cleaning up and also spent time with the major users to discover some areas needed to be redesigned. It's coming together!

Cindy

[BobWeaver]

I use OceanWest's 'Notes' database idea. Since you will already have Filemaker open, it doesn't add much overhead, you can quickly switch windows and enter your notes. This can eventually evolve into the help file. Also, have a few fields in it with some check boxes so you can quickly select whether it's a field, layout, file, etc., that your note refers to. The bonus is that you can search and sort your notes quickly.