Correct Documentation

[PaulSpell]

In the past the documentation I have provided for any database I have built has consisted basically of detailed user instructions and the Access Documenter output for all tables, form, queries etc.

As I work on my own it is difficult to know whether this is the norm or whether something further is required. Can someone tell me whether it is standard practice to also provide some kind of schematic representation or written description of program flow, i.e. which forms, functions and procedures are called from where and what they do etc.

 

[Oldsoftboss]

My first impression is to not mention how your Db is constructed. I am sure you have spent many hours (days, weeks, months) constructing your Db.
May I suggest your documentation be more of a help file aimed at educating your users in the functionality of your program rather that explaining how it works.
How many other programs do you buy that list how it was made.
HTH
Other views appreciated.
Dave

 

[PaulSpell]

That is true iro stuff that I do for private clients, but when I am contracting (working on site) it's a little different as the firm I am working for now want to support the database themselves once my job is done.

Therefore I need to leave them enough to fathom out how the things hangs together etc.

I suppose what I really need is some help on how to construct such a document. What format should it take (graphical or textual), are functions and procedures explained within the text or is it standard practice to leave that to the comments within the code?

 

[Oldsoftboss]

Give them your card and tell them to call you

Only kidding, haven't thought much about this, except that you say they want to maintain the Db themselves. Do they have much Access experience ?

If Yes, then they should be able to sort out things on there own.

If No, then it would be dangerous to give them any access to the code etc. (Remember when you first started mucking around with access). You can get yourself into real trouble real quick

Dave

 

[PaulSpell]

They are a large insurer and have their own development team, therefore as you say they SHOULD be able to work things out for themselves. But for some reason they want chapter and verse.

I would normally agree with you about giving them my card etc, but I want to keep them happy as they pay well and I may get quite a bit of work out of them in future if I play their game.

 

[Numpty]

Very interesting topic to me as well. I'd love to hear other peoples views on this subject as I'm in a similar situation. I took on a project to develop a database despite having very little prior knowledge - I wanted to learn and fancied the challenge. Anyway I've been completley on my own, apart from you guys!
So, my project is just about finished and the database is just about working, apart from a couple of reports and a few bugs which I'm trying to iron out and I've created a user manual but was unsure about creating some kind of technical manual. I have commented all my code but is that enough? I'll be leaving to go back to Uni in two months so I won't be around to support it.

Any chance of making this a sticky so we can get the senior members views on this?

 

[Mark Wild]

I find that this is often a problem, especically when you are working as a contractor. One of the biggest problems I've found is that people want the solution as quick as possible, and often try to reduce how much work you do up front (requirements analysis, data modelling etc). If you do this initial work to a decent level, it will provide you for the basis for both your testing and documentation.

My approach is that I document on 3 levels, a user guide, a developers guide and commenting in the code.

THe user guide is normally a word doc that is littered with screen dumps and is a low level step by step guide.

In the developers guide I try to explain issues such as security and a general overview of the whats and whys of your db. The depth of this is often up to the client, both on their expectations and the budget they have allowed for this essential part of the project.

On the coding front, I try to comment as much as possible, also explaining why things are done and where there are areas that are potential weaknesses/areas for change.

One thing I've picked up from another user on here (can't remember whom or I'd attribute it) was a summary at the top of your code. I've found it very useful when I look back at my own code, so am sure that it must be useful to other people as well!

     '----------------------------------------------------------------------------
                'Written:   Mark Wild
                'Date:      15/03/03
                
                'Process:   Move existing TB details into Archive
                '           Delete any records in archive with an 
                            archive date within 7 days of rerun
                '           Delete MBS and repopulate with new TB
                '           Delete any unwated recrods out
                '           Update data to expected format
                
                'Inputs:    Trial Balance(saved on network manually)
                'Outputs:   Newly populated MasterBalanceSheet
                '           Updated tblArchive withprevious months TB
                
                '----------------------------------------------------------------------

Everyone must be producing documentation, so I'll look forward to reading how everyone else does theirs.

Rgds,

 

[Len Boorman]

Interesting thread
My situation is interesting. I only develop application fro my employer but I am almost the only source of Access knowledge within the Organisation. Generally the other knowledge is limited to using a table like an Excell spreadsheet.

So when I develop an application I also have a bit of a question as to what to provide.

What I see and being necessary is:
1) Enterprise Rules. Basically the rules under which the application operates. What can be handled and what can not. E/g perhaps
Customer will have one invoice address
Customer may have mnore than one delivery address.

This I find a very useful document especially if you persuade people to agree it early. Yjey always change their minds later anyway.

2) Next an E-R Diagram. Picture worth a thousand words

3) Details of all tables.
Field Name
Data type
Field Size
Field limitations

4) Sometimes a document that purely discusses what can be done within the application. This is a "light" document. No technical bits, its just to give the flavour of the overall rationale.
Useful to give to senior management

5) User guide

6) Separate document discussing whatever security has been imposed. Get arounds, passwords, tweaky bits

6) Access created documentation

Now I am not saying that I always do all of the above. I hate writing documentation (as I suspect most people do). I am not looking to protect any application as my work or from any personal business point of view. Its merely that if I get hit by a bus then at least my replacement will have something to start with.

So that's what I do.

I can see all sorts of aspects to documentation. At present nobody here would have a ghost of a chance because there is no Access knowledge.
I do not think that you can teach Access via documentation.

Len B

 

[neileg]

Paul said

I would normally agree with you about giving them my card etc, but I want to keep them happy as they pay well and I may get quite a bit of work out of them in future if I play their game.

If they are paying you by the day then they will be paying you to write the documentation, too. I would be happy to be pretty full in that case, especially as this can only help your reputation with the client.

If they aren't paying for the time for writing the documentation then you still need to give a professional feel to this, but you can make it briefer, and therefore more high level. If you imagine your application as a black box, then describe the inputs and outputs in some detail (perhaps already covered in your user info), but more of an overview for the application itself, much as you suggest. Leave the program flowcharts out.

 

[The_Doc_Man]

I've found several steps to be nearly an absolute requirement for documentation based on the following observations.

1. No matter how long ago you worked on it, your name is on it and the folks who are stuck will call you. Even if you've left town.

2. When you pick it up after two years of being totally immersed in something else, even YOU, the author, will need lots of help.

3. You will need more documentation than you think you will need. Invariably.

4. Design decisions that were crystal-clear two years ago are all muddled beyond belief now.

5. If your client is like all other clients I've met, the problem has mutated faster than the client's support group could make fixes.

Since I have started working with the U.S. Government, I have learned WHY they earn the snide remarks about "it's not WHAT you write but how much."

In summary, I follow these rules when documenting a project.

A. All fields in tables and all controls in reports and forms wherein a comment or description or remark is allowed will have a meaningful one, even if it seems redundant at the time. ALL OPTIONS TO REMARK WILL BE REMARKED!

B. All VBA code will have the following classes of comments.

B.1. At the top of each module (Access usage of module here), I will have a brief expository lump in comments describing the general content of the module.

B.2. At the top of each SUB or FUNCTION, I will have a brief expository lump in comments describing the purpose of the entry point including the meaning of the input arguments and the nature of the output, if any. THIS INCLUDES SIDE-EFFECTS where you are taking advantage of scoping rules.

B.3. As a miminum, any code that involves transfers of control (to include GOTO, GOSUB, CALL, implied CALL, IF-THEN-ELSE-ENDIF, and SELECT CASE-END SELECT, will describe the reason for the test or call or selection. But any time I have a complex formula, I add comments when I have computed a significant term that contributes to the formula.

B.4. This sounds funky, but every END IF will have a comment that says "END - IF {situation XYZ} required attention" or whatever the matching IF really meant.

B.5. Where anything is DIM'd, regardless of the mnemonic value of that "perfect" name you chose, I add comments telling what part that variable plays in the coming operation, no matter how obvious. Now, sometimes I admit to using very short names like I, J, K (as opposed to loI, loJ, loK) when I'm using the short names for subscripting and indexing, so this makes the comment even more important.

C. As to separate documents, I build the following chapters into what I write.

C.1. Environment - a description of the business environment including the names of the data owner, customers of that data owner (i.e. intended users), and program versions for whatever tools I have to use.

C.2. Theory of Operation - a general overview of what the whole app is supposed to do, with sub-levels for ANY TRICKY PARTS. For instance, one of my probjects involves opening a Word document using automation in order to extract certain data elements from that document. (It's a form filed electronically and I do some data capture with it.)

C.3. Structure - a tedious list of every element in the program by name and location. This includes all DIM's variables in all modules, all SUBs, and all FUNCTIONs. Plus all data elements in tables. Plus anything computed by queries or on forms or reports.

C.4. Nature of Input - a tedious list of where data comes from that gets into the app. Include screen captures of input forms and text files, spreadsheets (if that is what is imported), or other files that you might use.

C.5. Nature of Output - a tedious list of where data goes to once it is in the app. Include screen captures of forms and reports as well as any sample output files.

C.6. Instructions on How to Use the App - a tedious list of all functions intended for the various user groups. As sub-headings here, I would put each user group and show what was intended for that group to do.

C.7. Maintenance instructions - Step-by-Step reminder of how the app was finally packaged including such things as doing a "Compile and Save" before the final button-down steps.

C.8. Corrective Actions - if this is not Maintenance but rather, what do I do if the data processing phase doesn't like something? This might not alway be required.

 

[PaulSpell]

Lots of very good advice as usual....thanks.

The_Doc_Man - Wow, you must need a wheelbarrow to carry all of that!

I don't think I'm going to produce quite that much, but I will certainly beef up the comments in my code and add some more info on the structure and design to the documentation.

I think someone already mentioned that part of the problem is not having the time to produce a detailed specification and design document in the first place, as users want everything yesterday and invariably change their minds half way through.

The project I'm working on at the moment has changed direction so many times I've lost count, so my initial draft now bares no resemblance to the finished product.

From what has been said here though, there doesn't seem to be a defacto standard, though most of you seem to be spending more time on documentation than me....something I need to rectify!

Once again thanks for the advice.