@Gasman the code link in Crystal's tool is broken.
@BigJoe9090
There are four basic types of documentation you might want.
1. System overview. High level. Talks about "what not how" in terms even an manager can understand
You can provide a link to the application menu here should the user want more detail. Start building a data dictionary as you write so that eventually every different field has a definition and validation rules defined.
2. Use Case. Identifies tasks performed by the system's users and provides details of how to find the task from the application menu and then goes step by step regarding data collection and calculations and finally output. After, you document from the user perspective, you might want to consider including references to specific forms/fields/tables. This is actually one of the most important aspects of documentation and it is ALWAYS done BEFORE you write the code and create the objects and tables to support it. This is what tells you what you, the developer, need to know in order to design the interface and schema and validation rules and all the other aspects of the code.
3. Schema. The overview is a diagram that shows each table, its PK, and its relationships with other tables. But it also contains additional detail that lists indexes and field defaults or validation rules including Triggers.
4. Application. The overview is usually the application menu. The drill down goes through forms and buttons down to code. Be very careful with this because there is the tendency to state the obvious but it is more important to convey the why of the code. Only explain code whose function is not obvious or which deviates from what might be considered "normal". Document changes as they happen. Usually, you will start by commenting out unused code but after testing the new version, all unused code should be removed. You can create a code repository for code you might want to use again rather than leaving it in place where you'll never be able to find it again and useless code just clutters the view and makes it hard for the reader to focus on actual details. At the form level, the most important documentation is the validation rules.
The easiest to create is #3 since much of that can be automated and is available using reports in Access.
#1 is important because it gives the reader context. You can start with a very skimpy description and flesh it out later. You
#2 is also fairly easy (after the fact, as in your case) because you can frequently get the users to do this for you. It is especially helpful if you can get multiple users to each write their own version of the use cases they use.
#4 is the most detailed and therefore the most difficult. You have to be very careful at this level because documentation that is out of date is downright dangerous. That is why you don't comment the "code". You explain what it does AND you always update the explanation when you change the code so this requires a lot of discipline. Less is more when it comes to code comments. Don't clutter the module with trivialities. Frequently, "why" is very important. For example, if you have an old application that you are converting. The old system didn't have good rules on validation so you might need to explain some validation choices. So, when you have a new record, you require both First and Last names to be added (always set the AllowZeroLengthString property to NO for text fields or else you'll be sorry). However, you don't want to punish the user for bad data that already exists, so for existing records, if this particular validation rule fails, you might want to give the user the ability to override and save the "bad" record. Just make sure that you haven't allowed the user to change something to nothing and you would use the OldValue property to help with this.
Some of your documentation should be built using Access. That allows you to build a data dictionary, for example but not repeat the validation rules in multiple places. The validation rules all belong in the dictionary rather than in the code or in the table description.
Here's an example of how documentation is incorporated into the application. Click on a report from the Reports listbox.
