Question Database Documentation

[branston]

Hi,

I have designed my database from starting with very little access skills (mainly thanks to you guys - thank you!!), but it is getting to the point where it really needs to be documented properly so I can hand it off to someone else any they wouldnt be completely lost! (I have been doing bits here and there as i go, but i know i should have been a bit more thorough!)

I know abut all the reports that access can output for you (Tools -> Alalyze -> Documenter) but i was wondering if any of you knew of any examples / templates of what a really good documentation should look like & include.

As I have just taught myself what i needed when i needed it, i have no idea what something like this should include so any help would be greatly appreciated.

Thank you!

 

[dbDamo]

I was going to ask the same question, saved me creating a thread. I'm looking at leaving my company in the near future (as long as someone else wants me!!!) and don't want to leave them with a Database they can use but don't understand.

 

[The_Doc_Man]

Documentation should address two main topics, with a literal Myriad of possible subtopics and some optional topics.

Topic 1 - How to Use It - including what it does, what options you have as a user, whether those options relate to how you are defined in the system, i.e. if you have security with multiple user roles, etc. What will it do for you? What do you need to do to get it to do each function you claim it to have? Why do you use it? Put it in perspective for the users.

Topic 2 - How it Works - for the maintainers, including how it got to its current state: From a FE/BE split, from replication, from whatever. Discuss relationships and queries, segregating same into structural vs. report-only elements. How do you build it? How does a user have to be set up to use it if they can't do so themselves. What extra s/w is needed? (e.g. for most earlier versions of Access, you need a licensed copy of Access on each user's terminal, whether individually licensed or site-licensed.) Where does the data originate? Where is it disposed? What external references are needed.

Topic 3 depends on your environment. In a government environment, you might have another requirement for a data dictionary that isn't necessarily part of the How It Works document. (In the U.S. Dept. of Defense, that dictionary is often mandated as a separate required document if the project exceeds a certain cost or scope.)

Topic 4 depends on the application. Is there a required periodic cleanup or other type of maintenance beyond simply compact&repair? I.e. inventory systems often have time set aside to remove obsolete records after an inventory reconciliation. You need to discuss how that would be done. For databases that don't have archiving requirements, this might not be such an issue.

A good rule to consider is to know your audience and vary your offering accordingly.

Users generally won't know doodlum-squat about internals. You mention a Dynaset and they will barf. They like to see screen captures and step-by-step instructions.

Maintainers don't want to be bothered with screens. They want to know data flow, theory of operations, etc. They want to know transformations, functional queries that relate to infrastructure, etc.

Operators (who usually have to end up doing the archiving steps) want step-by-step instructions but you can use computer jargon in that case. You can talk about specific directories and drop-down menus because they will probably know something about them.

Managers often don't understand details and in fact will glaze over at the first use of any technical term more complex than "hit the ENTER key." Therefore, if your company requires a manager's overview, scrub it to remove all jargon before publishing. If you ever read the "Dilbert" cartoon series, observe the pointy-haired manager and write to his level of technical idiocy... (Whoops! I meant "from a business viewpoint.")

 

[branston]

Brilliant. Thank you so much for your input The Doc Man. Thats just what I need to start getting my head around it. Not looking forward to this!! Going to have to write actual sentences again!!
Thank you!