Documenting database

[statsman]

Some time ago I did up an Access database for a friend. He told 2 friends and they told 2 friends and now several people would like a demo version of the database with documentation.

I usually don't give much thought to documentation as my databases tend to be stand alone to perform a specific set of functions.

Could someone point me in the right direction for the "generally accepted" method of Microsoft Access documentation. A template or somthing like that would be most helpful.

Thanks

 

[statsman]

This message is simply to place my original request ahead of the spam.

 

[Ron_dK]

Statsman,

You might check these :
http://www.access-programmers.co.uk/...+user+man ual

http://www.access-programmers.co.uk/...ht=user+manual

or a recorder for screenshots :

http://www.access-programmers.co.uk/forums/showthread.php?t=106978



Ron

 

[MarkK]

I don't see that there could be a "generally accepted" form of documentation any more than there is a "generally accepted" solution to any programming problem.

I can imagine that a completely comprehensive documentation of a system could be a bigger job than the system itself. And in developement, every db change needs to have articles updated in the documentation? Yikes!

I'd develop a very specific definition of the needs of the consumers of your documentation, and document for them. Are they Developers? Users? How much do they already know? About Access? About VBA?

 

[grnzbra]

When I worked with AS400/RPG, we had a utility that copied all the "flower box" comments in the code and saved them as a text document. This was then printed up as documentation for the internal operation of the system to be used by an ID department. You could do something like this by following starting each comment with an apostropy and an astrisk. Save the code as a text file and import it into a single field table. Then create a query that selects only those records where Left(Field,2) = "'*" and save the records to a table. Using the new table, loop through the records and save them to a string with carriage return and line feed between them and export this to a text file. Or something like that.

You will need to be careful about how you word your comments. One of the limitations on the system we used was that the comments didn't really tell the reader about what was really happening.

For example

If b <> 0 Then
c = a/b
End If

would be commented with "If b does not equal zero, c equals a divided by b".

That states the obvious. However, for documentation purposes, it would be more informative if it said "Check to be sure that b does not equal zero. If it doesn't, set c equal to a divided by b".

As far as how to use the application goes, we had technical writers to write documentation for the end user. When I've created end user documentation, I've always tried to write it so that the cleaning lady could sit down at the computer and use the database. It resulted in documentation that was annoying to follow once you knew how to use the system, but it allowed anyone to use it.

 

[Keith Nichols]

I'm too green to know about any accepted standards but I'm wondering what you mean by 'documentation'?

If your DB is anything more than trivial and has VB code in it, then comments in the code (documentation) must be essential to be able to support that code. I know, even with the code full of green, I still sometimes look at it and wonder what it is for - obviously my documentaiton is not as full as it should be -

I have created some more formal documentation to assist the users and future administrators. One thing I find useful is flow charts, created in Visio, to show the functions of various forms and processes within the DB. A new owner of the DB can review this and get an idea of what I am trying to do rather than looking at 6 screens of code and scratching their heads.

Hope this is of interest.

 

[abubasil]

Documentation !
Well, I like to share with you my vague version of 'simple documentation system' database.
I imagine a department of purchasing or contracts..this dept. has some sections , each has few employees work in it.
each one of these employees maintains a requisition or purchase order to chase ..and there will be an employee for documentating their correspondences with companies in this way.

 

[jdraw]

statsman,

I agree with MarkK in that it really depends on the audience. A User guide with start up and activities/scenarios may be appropriate for some. But for technical maintenance, design changes etc, a more complete and detailed document(s) with code listings etc and good in line comments related to purpose,parameters, called functions.... And the competency of the audience will usually dictate a "level of detail required".

Another way to look at this may be -- What would you expect if the tables were reversed?

 

[vbaInet]

jdraw, I'm not sure if you noticed that this thread is 7 years old?
It was only resurrected by abubasil.

 

[jdraw]

vbaInet,

Good point - I didn't. I saw the "response" from abubasil.
Thanks.

 

[vbaInet]

I suspected that was the case

 

[gemma-the-husky]

I find it a pain that you cant annotate queries, (and forms and modules) easily. Getting at the description is too awkward. It ought to be easier.

 

[vbaInet]

Getting at the description is too awkward. It ought to be easier.

It's logical though. We can't expect the Description to be in Access.Forms(x) because that refers to the object and not the container where the object resides.

 

[Royce]

Seven year old thread, 20 year old product, and there is still not a good solution for Access Documentation and/or Help!

 

[gemma-the-husky]

I suppose its little different to documenting anything.

documenting a spreadsheet is none too easy either.

 

[jdraw]

Seven year old thread, 20 year old product, and there is still not a good solution for Access Documentation and/or Help!

Royce, do you know of some development/database tool that is self documenting?

"20 year old product,"--- something must be working for user/developers.