Interface Design and Why the Light on the Man's Head Glows

One of the common phrases that comes up a lot here, especially with respect to interface discussions, is the phrase "What vs. How." I usually forget to think about what this really means, but last night I got a vivid illustration of the concept.

We were driving home after a nice dinner of tacos and margaritas, me and my husband in the front, my 3 1/2 year old son stuck, as always, in his car seat in the back. He'd had Show-and-Tell at his pre-school that day, for which he'd shown a rather interesting truck he received as a gift at some point. This "Discovery" vehicle  has a long handle so he can run around pushing it. Why this toy is interesting is that it talks, glows, etc, but is completely battery free. In fact the whole thing is supposed to be environmentally friendly, recycled plastic, etc. There is a little man that sits in the drivers seat wearing a helmet with a light. When you run around with the truck, the light glows and the man tells a story about Africa (completely unintelligible, but well-intentioned nonetheless).  Obviously the truck was quite the hit at school, leaving my son burning with questions.

Ewan: Can I take the truck to school for show and tell next week?

Mommy: Sure

Ewan: Does Liam have the same truck?

Daddy: I don't think so, but you can share yours with him.

And so on …

Ewan: Mommy, why does the light on the man's head glow?

Hmm, that's a tough one. Do I make something up? Do I say I don't know? I decide to trust in my son's maturity and curiosity and try to give a real explanation…

Mommy: When you run around with the truck, that's a lot of work right? That work from pushing the truck is what is called kinetic energy, and it gets transferred into the truck through the wheels, which is changed into light, making it glow. Does that make any sense?

Silence and a strange look from my husband...

More silence from the back seat...

Ewan: Daddy, why does the light on the man's head glow?

Daddy: So that the man can see.

Why is this interesting? Well, apart from giving you some insight into the personality differences between myself and my husband, it is also a pretty good metaphor for how one should approach interface design and documentation.

Case in point - one topic on 3D Interop which has always been a little confusing for me is our Callback Mechanism. The documentation states:

3D InterOp Connect interface provides a callback mechanism on translated entities. A member function of SPAIConverter, SetConverterCallback, is provided to set the callback function.

...

This function takes four parameters. The four parameters are:

• pInputEntity is the input entity.

• pOutputEntity is the output entity.

• pInputEntityType is the type of input entity.

• pOutputEntityType is the type of output entity.

Hmm. That explains how to use it, but does it explain to the user why they might want to?

A different explanation might be:

Applications that have internal user defined attributes which are currently not supported by standard 3D InterOp attribute transfer can use the Callback mechanism to translate these attributes. It provides access to both source and destination topology during the process of construction - at that time the source can be queried for any piece of data so that it can be placed on the new topology as it is created.

You might notice that in my attempt to explore What vs. How, the explanation actually got longer… Rats!  Well, I did write it after all, and I am the person that forgot to tell my son that the light glows so that the man can see.