Documenting a Access Application for Developers

views:

answers:

+2 Q:

Documenting a Access Application for Developers

I need to document a MS-Access application that was created, developed and maintained completely by a power-user over 10 years.

This is an interesting situation because what they want is a manual so that a future developer can come in without prior domain knowledge and make changes to the frontend or the backend in a timely manner.

There are a few questions on my mind for this little project:

What is a good manual design creating application? Microsoft Word doesn't quite cut it.
What kind of things would you, the developer, need to know in order to make changes to things like forms, reports, tables or other Access objects?
Anything else I missed? Any pitfalls?

+2 A:

You could start with generating some automatic code documentation using MZ-Tools add-in for VBA. The same add-in can help you clean unused variable declarations, generate line numbers, reorder procedures within a module, etc.

Documenting forms is more difficult. My proposal would be to keep a screen shot, alltogether with a .txt file obtained through the undocumented application.saveAstext method.

Philippe Grondier 2010-05-27 15:07:04

Thanks for the tip on MZ-Tools. Are there any other MS-Access/VBA tools out there similar to that? Also, the amount of VBA code in this application is near zero. It's *all* pretty much in Access objects.

Nitrodist 2010-05-27 18:38:27

+2 A:

In my experience, Access and VB6- based programs are plagued by more code replication and technical debt than programs in mainstream languages. I'm not sure why. Maybe it's the nature of Access as a "prototype" or "toy" database (though it can be quite powerful when yielded correctly).

If I had to choose between expending time on documentation and expending time on reducing technical debt, for example by remodularizing, eliminating repeated code, splitting long functions, etc., I would choose the latter. The improvement to maintainability and readability would be greater.

Uri 2010-05-27 15:11:26

I would say it's the result of Access being so easy to use that people who don't know anything about best programming practices are able to create applications in it. It's not Access's fault any more than it's HTML's fault that there's so much "tag soup" out there on the web -- it's a FEATURE not a BUG.

David-W-Fenton 2010-05-27 17:47:58

I would second your actual recommendation, though -- refactoring for maintainability is going to be a much better use of a developer's time than thoroughly explaining how the strands of spaghetti relate to each other!

David-W-Fenton 2010-05-27 17:48:56

@David: When I was in high school and freshman year of college, I made supplemental income of fixing databases for people who wrote applications without knowing anything about database normalization.

Uri 2010-05-27 17:50:59

@David, unfortunately, almost all of the application is in Access objects and not VBA other than what is generated by default for opening up the reports/forms.

Nitrodist 2010-05-27 18:43:06

@Uri: I'm 30 years out of high school this year, and I *still* make most of my living from fixing Access databases created by people who don't know what they are doing. It's not a flaw in Access -- it's actually one of its greatest strengths, because it enables those without a high level of expertise to create something that is useful.

David-W-Fenton 2010-05-29 01:50:23

@Nitrodist: Access objects document themselves quite well. For example, a main form/subform indicates a parent/child relationship between the tables involved.

David-W-Fenton 2010-05-29 01:51:48

Have you tried the using the built in database documenter? It will print out all tables, indexes, forms, controls, each property of controls. Code, the sql used and just about any thing else. This results in huge, but just massive printouts. However, while it will kill a few trees in the process it sure is a great way to impress the boss.

Albert D. Kallal 2010-05-28 02:37:23

Yeah, I've taken a look at it and, like you said, the results are huge. Since the tables aren't formally linked with FK's, it misses a lot of of those relationships. It's not exactly the greatest tool when it's generating over 200 pages XD.

Nitrodist 2010-05-28 11:44:47

Future developers who have to work on the project would thank you if you took the time not just to document the app, but to implement proper referential integrity. And, yes, it would likely involve significant data massage to fix up or delete orphaned records. I've done this a bazillion times when hired to take over apps created by less-than-stellar developers. It's usually the first thing I'd do before any real work to enhance the application itself. Working on a front end with a crappy data schema behind it is like trying to polish a turd.

David-W-Fenton 2010-05-29 01:54:32

Yeah, this little project has 2 phases. Documenting the current project as it is right now and then myself creating a second version that's properly made which will most likely be an adventure.

Nitrodist 2010-05-29 20:09:31

Is it worth documenting the stuff you're going to replace with something better?

David-W-Fenton 2010-05-30 19:17:02

Yeah, it's going to be months. @David-W-Fenton if you can summarize your thoughts you've made made in the comments as an answer, I'll accept it.

Nitrodist 2010-06-11 20:46:40

Too lazy to bother.

David-W-Fenton 2010-06-11 23:45:55

ansaurus

tags:

views:

answers:

Documenting a Access Application for Developers

related questions