Design choices: training vs. documentation vs. one-time developer fix

[psemianonymous]

The full list is:
training vs. documentation vs. many developer support-calls vs. detailed programmatical system


So here's an example pulled from my recent past: how do you go about setting up a lookup table? Editing it? Changing items in the table's names (yes, actually changing the existing references to the new name)? Deleting obsolete entries and changing their values to some other entry in the table?

I had to answer questions about all of these things. You see, in my application the only way to get to the lookup table was during data entry. There was no menu item that takes you directly to the little form that allows you to enter lookup items, at least until this recent program 'evolution' that forced me to change.

So let me explain: this form is very simple--it's a bound form bound to the lookup table itself, with record navigation buttons and a record selector on the left (in case anyone wants to delete something). The lookup table has just the one field--the text field itself--and so this is the very height of simplicity.

But I was asked because the one specific user doesn't know exactly how to fix this. This is fine, because I never imagined this would be an issue. Who goes around messing with existing data? So I don't even have documentation written in the program manual for how to deal with these lookups, in any way, besides during the data entry process. I don't even think there's a single screenshot of the form there.

Nor did I show my users how to mess with the the lookup form itself, because there's a lot of them. And again, I never dreamed they would want to do something like this. So I've totally failed to provide them with any sort of instruction as to how to do this by themselves, so by default they call me. Which is fine, but I'm now wondering: should I have done something different?

I don't know, and that's the problem. Maybe I should have made a menu item for each of the lookup table forms (now all have been added under the 'Misc' tab). Maybe I should have just added a spot in the documentation for how to mess with each lookup table, or added a general section explaining how to do each specific task in general (e.g. 'how to delete a record from the table, assuming that's allowed' or 'how to edit dictionaries' or whatever). I don't like documenting things that I believe will never be read, because I absolutely hate writing documentation.

I could have programmed in a super-flexible wizard that performs the task for the user--but it would only be used perhaps twice or so, so what's the point of doing all that programming so that for two seconds your user doesn't need to think? Plus it's a lot of work, and it's a whole lot of work to get that sort of thing right in any fashion, or to be absolutely sure that there won't be confusion and/or misuse of the wizard.

I could have spent an hour during their initial training session explaining how the lookup tables work and such. Unfortunately, most of the people I work with are too practical to care, so teaching them things they don't care about (at that moment) is talking to dead ears. Even if I did explain how to modify the lookup tables in several theoretical situations, there are a lot of these situations to cover. Besides adding a new entry (covered), we could discuss things like changing all instances of 'foo' to 'bar' and also all instances of 'foo1' to 'bar' as well. Or things like explaining the difference of changing the value 'foo' to 'bar' vs. changing an individual record's value from 'foo' to 'bar'. Or attempting to delete 'foo' from the lookup list, and what implications that has.


So the deal is: with any reasonably-sized application, your users will not be able to figure everything out by themselves. So inevitably they will call you for help on things you never dreamed they would be doing. The above is just an example, but this is just one more design decision you have to make--this lookup table example is just one of many different situations this decision happens. What I'm looking for is specifics--specifically, what does everyone else do in this situation of modifying the face of the lookup table? Or for requests for new reports, or for things like assuring quality data entry, i.e. preventing bad data entry?

These are some of the design issues I'm thinking about presently.


Pete

 

[LarryDeLaruelle]

Pete:

An interesting question and full of potential 'unintended consequences'.

Letting users tinker directly with lookup tables can result in lots of those. Change 'foo' to 'bar' all the reports based on 'foo' are 'fooey'.

I use combo boxes to permit the user to select the desired item and provide an 'on the fly' method of adding new items. This allows them to add to but never modify or delete entries.

There are instances where it may be necessary to actually edit a particular lookup item, but the users, especially the person who hired you to design the db, need to understand the ramifications of that change. Databases are used in dynamic environments and will always need to be tinkered with in some fashion or another else we'd all be looking for other employment.

Maybe I'm paranoid but I prefer to give users as little control as possible over the data -- entry forms to get it in and reports to get it out.

For what its worth, that's my two cents.

Larry De Laruelle
ldelaruelle@familychildrenscenter.org

 

[assets]

Pete;

People I found do not resd documentation. What I did was to write help files. By either pressing F1 on the field you are in or clicking the ? and moving the ? over the field will load help for that field. This was written in the day the database was in 97. When I wernt through 2000 and XP. I also added HTML help which has more user friendly search. Yes it is a lot of work to set up and if you need to change it takes a very time. Having something like lookup is a way of not having to write all this, But I like having help in each area.
.

 

[psemianonymous]

Re: replies

1. In my next application I'm going to make the simple lookup tables just do what Larry has suggested and prompt if the user wants to add the item to the list, or search for a different item. That will cause a few typos here and there, but nothing that isn't already happening in some fashion. The only thing that stopped me is that the database already had a fully-working system (in this regard, anyway) in place when I was tasked with 'upgrading it'. Compound this with my niggling suspicion that things like I described above would happen, and so I ended up with one form per lookup table. Anyway.

2. Yeah, I hate writing documentation, primarily because it is so difficult to write useful documentation. Sure, we can all put out a list of things 'click here. form opens, choose file menu, click save, a dialog opens, choose browse, etc'. But actually describing why you need to do this cryptic set of commands in the first place (this is just an example) is my goal. My users should fill out every field because they know the consequences of not filling out each field (please enter accurate dates, we use that for accounting on the Blah1 report).


I just feel like I'm doing something wrong with the design when the users call on things like this. I have to remember that this is an acceptable wrong[1], which people take for granted, and that getting it 100% right is (near) impossible.

Oh, and I'm not on any sort of contract--I'm in-house, so there's no billing concerns. I'm here doing other things anyway (or not--this post is an example of what I might be doing).


Pete
--
[1] - "acceptable wrong" - as opposed to 'unacceptable wrong' - sometimes called 'honest mistakes'. With a subject as complicated as design, it gets to where you can't say 100% whether something is wrong or right, just what becomes easier and what becomes more difficult as compared to alternatives--you try to find the 'best' alternative. So if something goes wrong with your program, we just take it in stride, so long as nothing fatal occurs. Minimize casualties, don't attempt to eliminate them altogether.

 

[LarryDeLaruelle]

Pete:

I do most of my work in-house also although I do have a few outside projects. They are all for non-profit orgs so I don't make as much as I might, but they are usually more appreciative and are willing to work with my schedule.

I have found, as you have, that allowing users to enter new items in a lookup can result in duplication. I just finished recoding a bunch of records in our HR database because the data entry person was taking very literally what the review was writing on the interview form for outcome. So we ended up with several versions of essentially the same thing on a few outcome types. Keeps me busy and out of trouble so it not a bad thing.

Like you, I hate writing user guides. They have to be written for the lowest common denominator and some users find that insulting. Also, they may be looked at once or twice and then disappear into some file never to be seen again.

Documentation on the other hand is critical and I frequently kick myself for not writing better documentation when I have to go back and try to update/revise something and have to spend time tracking everything down.

I'm tinkering with a database solution to documentation and, if I get it working and keep the entries up to date, it may help streamline the documentation process and make retrieving documetation notes easier. We'll see.

Thanks for starting this post. It's a good topic to kick around. I'd like to hear from some of the gurus on how much or little documentation they do and what form it takes.

Larry De Laruelle
ldelaruelle@familychildrenscenter.org

 

[psemianonymous]

We've had some interesting discussions on documentation:

here: thread1121-840815

here: thread181-809051

here: thread702-488001


Though I would still be interested on what others' perspective is--I'm not ending the conversation by linking, just pointing out that there's been some interesting stuff said in the past, too.


Pete

 

[LarryDeLaruelle]

Pete:

Good links, thanks.

I'm beginning to think that one's approach to documentation is as individual as designing databases. I'm pretty much self taught (with much assistance from the Tek-Tips folks) and have probably missed some of the finer (or esoteric) aspects.

I've been doing database development seriously for about five years and have tried a number of approaches to documentation. The only thing I do consistently is to add a lot of remarks to my code and keep a revision list whenever I make significant changes.

Is there an established format for documentation (something like Hungarian Notation - funny link by the way) or is it something each developer needs to create?

Thanks again for starting this post and continuing the discussion.

Larry De Laruelle
ldelaruelle@familychildrenscenter.org