Documenting Database 2

[perrymans]

I am ready to begin documenting my database, as in Help files and user guide, etc.

What is a good resource to learn more about best practices and methods? I have never done it before, and don't know how it works and is organized.

Thanks. Sean.

 

[perrymans]

Bump

 

[jrbarnett]

For producing documentation for application users, the best way I have found is to imagine myself as a user and think about what I would like to know about this application in both the how to use it and how it relates to any business processes that they use, plus any hints/tips for using it and help contact information.
From a technical point of view, while using a help file or HTML readme is by far the most common form, I've had a table with common questions and answers, accessible via a menu option which lets the user view the questions and answer on screen via a report and print it out.
This works well, because it makes adding new entries or changing existing ones far easier than generating a new HLP or CHM file.

I don't think that there is such a thing as best practise as far as user documentation is concerned, because each application has its own reason for existence, quirks and business processes to support.

Talking about technical documentation for developers, DBAs and IT support staff is another matter, and should include fully commented source code, with sensibly named objects and controls in accordance with a defined naming convention, 1st and 2nd level entity relationship diagrams showing table relationships. Basically, anything that you would want to see if you were coming into the project at that point to take over.

John

 

[perrymans]

Thanks John. Any chance of outlining the table structure and how user's search/ access the information?

Can they use F1 on a form to get to an entry about that section they are in?

Do you use the "What's this?" feature at all, meaning that little pointer with the question mark?

Thanks. Sean.

 

[jrbarnett]

Something like:

HelpID - Autonumber - primary key
HelpDescription - Text
HelpText - Memo.

You could add a comma separated list of keywords for searching as well if interested, just add a button to run DoCmd.RunCommand acCmdFind.

Create a new tabular form bound to this table with the HelpID hidden from view and the HelpDescription taking as much width as possible.
An open button at the bottom that opens a report in preview mode, passing the ID across and retrieving the description and text. Give whatever facilities you need to let it print on any installed printer on the PC.

No, they can't access it via pressing F1 and I don't use What's This?, but you can get around this by putting a "Help" button on an appropriate form which opens this form at the approrpiate page.

John

 

[jrbarnett]

Oh, and you might want to look at thread669-820939 and thread669-892371.

John