minimal example

An idea by CL, suggested on the page titled Effective ways to request help with Tcl-related problems.

Some suggestions:

  • hello world, of course

Whoops... (jcw quickly recovers and removes the false start...)

Before we go farther, CL should mention that he had a quite different notion in mind. This is the model context: a developer is working on a program. His results don't satisfy him. He decides it's time to seek outside help. How does he communicate to his colleagues the problem?

I claim a crucial notion in this communication is that of the "minimal example". The programmer might require a GUI that displays certain files and their characteristics. Perhaps he doesn't know how to program this. If he says, "I can't make it work!" and stops there, he's unlikely either to receive prompt help, nor to make much progress on his own.

If, however, he says, "I think I can handle the GUI part, and I know how to sort the results, and decorate the framistan, but the heart of my difficult is that when I use the command

  exec ls *.$extension

I get [specific error message] rather than the list of files I expect", then chances are someone will answer him crisply and effectively within seconds. I call the ordered triple of "exec ls *.$extension", the expected response, and the observed response, a "minimal example" of the programmer's problem.

LV In my early developer years, I worked on one of the first commercial offerings of Unix. The company's support people were always hammering on me to provide, with my bug reports, a small, coherent example. I was always agrevated when they said this. I mean, the bug I was having was always in some huge program, and trying to duplicate the thing in something small seldom worked. I always blamed the problem on the compiler's inability to handle larger complex programs...

This comment by their support is now one of the mantras I chant when dealing with users. The situation, from my perspective, is this. A vague description will in most cases be 'tossed' into a pile that may someday be looked at if I get bored. A specific problem description may intrigue me enough to take a look at the problem, but will also go into said pile once something more concrete comes along to be solved. A large complex program will go into a smaller pile, and may even be looked at occasionally. But small coherent examples, with specific descriptions (particularly if said problems are reproducible), go to the 'top' of the list of problems on which I spend time, because I get the most 'bang for the buck' in terms of solving problems. The others get worked on when the top priority list goes empty. However, if that seldom happens, then the other problems seldom get addressed.

But what, you may ask, if the problem is a show stopper - something that results in the developer reporting the problem cannot move forward? The more information they can provide, experimenting they can do, etc. helps. Also trying out the latest version of the software helps - perhaps there are old problems causing problems that have been fixed.