March 7, 2023

Write A Great Feature Request

Hi! I’m Jessica Brown, from Miskatonic University (MU). I use Tinderbox every day to allocate time on the various time machines on campus. I don’t know how we could manage without it!

Remember: you know who you are, but the software developer doesn’t. Your email address might be sufficient, but often it's not. It also helps to give some sense of what you’re doing, and how familiar you are with the product.

It is also a good idea to communicate a sense of your purpose here. Are you proposing something that might be intellectually interesting, or something you need next Thursday? Is it something you need just once in order to finish your dissertation, or is it something a hundred people will use every day?

We currently have no fewer than 17 time machines, but each of them has its own constraints. The machine in the basement of Severance Hall, for example, is only available during the day, while the machine in Performing Arts is available 24/7 but reserved on weekend evenings by the Theater Department. The machine in Somerville was built for the Women’s College and is not very comfortable for people taller than 175cm. The machine on the roof of Holmes Hall must be primed with burning tobacco, which can cause problems with allergies. When a professor wants to reserve a machine, they fill out a web form ( This sends me an email which Tinderbox parses into a note with the request. An agent, which is linked to that note, then finds time machines that might be suitable.

People are often tempted to abstract away all the detail of their work, or to assume those details are self-evident. In my experience, it can help a lot to have some perspective and some sense of the details.

The agent works really well! I’ve attached a simplified version, one with just three time machines and a single reservation request, so you can see the details. I know this is a very simple-minded use of Tinderbox!

Everyone says that they’re a novice, that they’ve scarcely scratched the surface. There are many different ways of being a novice. One person is “only using the easy parts” but knows them thoroughly. Another is a professional developer, but only started with Tinderbox yesterday. Having a small example lets the developer see what you’re actually doing.

The agent is very good at saying, for example, that Professor Higgins could use Severance on Tuesday or Holmes on Sunday night. My problem is that Professor Higgins inevitably calls me to ask why he cannot use the machine in University Hall instead. Can an agent — or something — tell me what part of the request rules out that particular machine? Is the Attribute Browser pertinent?

Clearly identify your problem. This is perhaps the very best use of bold fonts.

Context helps. Here, we understand that the information for which we are looking is likely to be requested by phone, at an arbitrary time.

As it is, I have to fiddle with copies of the agent, changing queries until I find the issue. This is slow and prone to error, and mistakes make people suspect that we are arbitrary or unfair in assigning time machines. In the sample file, you’ll see that University Hall is not suitable to Jane Doe’s project; how could one display why each unsuitable machines was excluded? (In this case, the answer is that this machine, when not in use by the administration, is reserved for digital humanities research and Professor Doe is in Physiology.)

A small sample file lets the developer focus on your problem without wading through extraneous detail.

Have other ideas about feature requests? Email me.