Do you have the Advance version? If so create Database Design Report (DDR)
If not then I recommend upgrading to the Advance version.
I have FMPA and I am using the DDR. I was looking for suggestions on the document content.
I would push back hard on the "hard copy" aspect of it. Unless the client is ok with the HTML DDR as schamblee mentions. Something like a BaseElements analysis or Inspector Pro analysis is better than any Word document that you can put together. And is going to be cheaper to generate.
Unfortunately they insist on having user readable documentation. While I don't have a problem doing it despite the hard work I quoted a fairly outrageous price figuring they would think about other alternatives. They want what they want and are apparently willing to pay through the nose for it.
Then written documentation to supplement the DDR (and possibly other analysis).
I like to print to PDF all table/fields and scripts, in addition to DDR. These are more quickly searched for what I need.
I created HTML files as a "help" for each layout (the elements, the flow, the functionality) and these are printable as pdf (or printer).
I create HTML files as a "help" for each layout (the elements, the flow, the functionality) and these are printable as pdf (or printer).
I'd be interested in hearing more about how you do that! It would be great to see an example if you have one you can share.
In the past, I've added context-sensitive help systems to placate clients who wanted written documentation. It's really easy to set up. Add a help table to your file with a few fields including a key, area, topic and description. In one case, I added a container field for a screenshot and a second container field for a movie.
Next step is to create a single, very simple script which opens a new (smaller) window and searches for the key you send via a script parameter. Then you can put help buttons (usually just a small question mark) in relevant locations and make those buttons run your help script with the parameter. The end result is that the end user can write their own help system based on their procedures.
In your case, you could also create a printable version of the help table data, sub-summarised by area and topic. They'll probably never print it, but at least you will have fulfilled their request.
Some documentation is good but follows the law of diminishing returns.
The more comprehensive the documentation the more costly it is to maintain.
Your benefactors need to know that any good FM developer to follow you would benefit more from knowing the business process and problem domain (the why of the design decisions in the solution) than have a external schema document. Any competent developer can get all of the details from the solution itself.
Fully agreed with coherentkris
The specs / use cases are more important because they describe what *should* happen. And perhaps an ERD.
The solution itself can be documented by running a BE analysis (or other tool) which is the first thing that any FM developer would do anyway instead of reading the document. I know I wouldn't give it much consideration.
It is likely to cause confusion and aggravation if it is not kept up to date.
The only thing I would want to see documented is any naming conventions.
My current job came with a "Winchester Mystery House" database solution. It's had stuff "bolted on" thru many years and versions. When you pop the hood on any given subsystem, you never no what crazy stuff you'll find.
I've just added a context sensitive help system so that I can help users get up to speed on the new features as I remodel as well as brief entries documenting any non-obvious design changes in order to keep my fellow developers up to date.
The trick that I wanted to share here is that the help window shows a list of titles to click to open a "topic". Full access users see a list of titles for both users and developers. General users only see the topics for users.
Thus, I can use the same tool to doc both how to interact with the UI and also how it is designed.
for those of you don't know the Winchester reference:
it's a real hodgepodge of construction night-mare!
That (regrettably) exactly describes the database that was handed to me when I started work for my current employer. I actually find scripts that use things like:
Copy/paste instead of set variable/set field
Looping thru portal rows to work with related data
Layouts that allow/require users to directly edit (in an edit box) foreign key field values and even (gasp) primary key fields
As well as numerous design features that use "brittle" methods that "break" when simple changes occur such as personnel turnover or transfers.
It keeps me busy retrofitting since I usually end up fixing a dozen other things that I find in the process of making the original change or fix....
The documentation trick that I described makes it very easy to leave notes for myself and my team members so that I improve both the design and its associated documentation.
my mantra (after 'backup, backup, backup')
is 'comment, comment, comment'