API Penetrability

A recent usability study highlighted some issues related to API penetrability (you'll find a posting from my colleague who ran the study here). Penetrability refers to the extent to which the developer using an API needs to understand some (or all) of the underlying implementation details of an API and the extent to which the developer is exposed to those details.

A colleague of mine recently completed a study on Avalon. During the study, she investigated compound properties in XAML. Many properties in Avalon are reasonably simple and can be assigned values in XAML by creating a string that represents the value and assigning that string to the property. Behind the scenes the string is parsed and the appropriate value is assigned to the property. For example, if I have a Button I can set the background color of that button to Red like so:

<Button Background=“Red“>Hello World!</Button>

However, if I want to set the background to be an image I need to pass in the path of the file that stores the image. I can't simply pass in the path to the Background property as above as in the case shown, a color is expected. Instead, I need to use a compound property. A compound property is a property of an object that can be assigned a complex value, such as an instance of some class. To set the background property to be an image, I need to create an instance of an ImageBrush and set the background to that ImageBrush like so

<Button>
<Button.Background>
<ImageBrush Path=”image.jpg”></ImageBrush>
</Button.Background>
Hello World!
</Button>

In order to know that I can set the Background property to an ImageBrush, I need to know that the Background property is of type Brush and that ImageBrush derives from Brush and that therefore I can create an instance of ImageBrush and assign it to the Background property. But there is no way to know that from the XAML syntax alone. Furthermore, there is no way to infer this from the simple case shown earlier where I set the property to Red.

In the usability study mentioned above, participants had difficulties with this task primarily because they did not know the type of the Background property. They had no idea what they could do with the Background property.

One solution to this problem would be to add a feature to a XAML editor such that when the mouse hovers over a property a tooltip is shown that displays the type of the property. This wouldn't alter the extent to which the developer needs to know the underlying implementation details of the API, but it would alter the ease with which they are able to get that information.