Documentation

[AnnMarie]

Can anyone refer me to a source that demonstrates how to thoroughly document
a database application? Perhaps something with examples or a sample form
template?

Thanks!
AnnMarie

 

[Larry Daugherty]

Hi AnnMarie,

I think most experienced programmers and software engineers coming
into Access agonize for a while over that issue. I always thoroughly
document my procedures including all event code (all of which also
have error handling) and not much else. I do a fairly righteous job
of creating the front end documentation: Problem Statement, Product
Specification and Functional Specification. Those documents give a
pretty good idea of what I'm trying to achieve.

Beyond the above, most of my documentation is aimed at the user via
Help files and the like.

If you are so inclined you could document the purpose and flow of each
form and report with a lengthy comment block at the head its module.

Due to the difficulties of documenting a graphical system I think that
most of us just don't do it very well. FWIW most text book examples
aren't documented as well as I do.

Simple graphic controls are too self evident to bother about unless
you have event code. Some of the more complex procedures such as
callback routines are worthy of significant documentation.

There are third party tools to help you document your procedures and
add error code. MZTools is one such. Just getting that much would
give you a running head start.

As for *thorough documentation*, maybe some of the wiser folk here
would chime in.

HTH

 

[Amy Blankenship]

I have autotext in Word when I type the words "New table" that inserts a
Word table that has a header area with fields for the name of the table and
its purpose. Each field in the table then has a row with columns for the
name of the field, its data type, whether it is the primary key, and its
purpose. I often use hyperlinks for FK fields to point to the (word) table
that describes the (Access) table that the FK points to. I find that
autotext is also very useful for frequently typed phrases, such as "unique
identifier of this ".

When I document code, I document it inline. Since the database application
is not usually relevant to the end product of what I do (it's just a quick
and dirty way of getting data in there in the early stages of development),
that's usually sufficient for me.

HTH;

Amy

 

[Daniel]

There are various option available to you.

i) make a word document (also seen html) as a support document
ii) create a custom help file and link it to your database

Larry is also right with what he wrote, that you should try and document you
code and tools such as MZTools are great for speeding up and normalizing it.
you can get a free copy at http://www.mztools.com

So good source of information on this subject include
http://frogleg.mvps.org/helptechnologies/htmlhelp/hhaccess.html
http://www.danish-shareware.dk/soft/shelpm/index.html

Hope this helps,

Daniel

 

[Public]

Total Access Analyzer is also a good documentation tool (www.fmsinc.com).
It produces numeous reports, many of them are hierarchial in nature so you
can see what queries are referenced by a particular query.

This app may be overkill for your purposes and most individuals find it
pricey but given the number of hours it would take you to create a tool even
half as sophisticated, it's a real bargain.

I have also made my own simple tool which just grabs tables and queries and
their fields. It produces a much more compact report than the built in
documentation report and also includes properties that the standard report
doesn't include such as description. I used the tabledef collection to
extract the data and then I write it to a table. The reports are based off
what is stored in the table.

 

[Jeff Boyce]

AnnMarie

For whom?

If you are documenting the internal functioning of an application for those
who will have to maintain it after "the beer truck" gets you, you already
have several excellent suggestions/responses.

If you are documenting "how to use this application" for users, NONE of the
preceding will be of any value! As my spouse loves to remind me, she "just
wants toast" and doesn't care how the toaster does its job.

If your application is built with the end-user in mind, you'll include
ToolTips to reduce the need for HELP and for a manual. If your application
organizes the processes in a way the end-user understands, you'll have less
need for HELP and for a manual. If your application hides the complexity of
the underlying database, ...

And you may still end up creating a User Manual that gets used primarily by
someone new, without any knowledge of the underlying business need!

Good luck!

Regards

Jeff Boyce
Microsoft Office/Access MVP

 

[Larry Daugherty]

Dang! Then I guess it's a waste of time to create Help Files for the
user since you've judged them to be useless to the end user. I can
save myself a lot of time and effort.

 

[AnnMarie]

Thank you all for the suggestions. For my own records, I usually create a
Word document that lists Tables/Queries/Forms, etc., the Source (where data
is being pulled from), and then Comments (short description of what the
object is). I've had someone from an external office request a copy of the
database, and I wanted to document the application for their IT Department
(not the end users...I already have a User Manual for them) in case they need
to modify the design. I thought perhaps there was some type of 'industry
standard' for documentation. Thanks also for the links to the documenting
software!

AnnMarie

 

[Jeff Boyce]

I wouldn't rate HELP as useless. But if you could prevent the need for HELP
in the first place?!

Regards

Jeff Boyce
Microsoft Office/Access MVP