The story of choosing an API - stumbling through a jungle of selection barriers

Summary: A user experience a selection barrier when he/she is faced with multiple choices for accomplishing a task but is unsure of which one to select [1]. I recently experienced this as I was beginning to do text analytics in MATLAB. In this blog, I document my trip through a land of many choices trying to figure out a single file reading function to use and how I wish the experience had gone better. Finally, I

Text  analytics is a hot topic these days. I came across John Laudun's Text Analytics 101 when browsing for an intro article. The article walked the reader through an example that involved revealing language usage patterns in a short story based on the frequency of words. A light bulb lit up in my head: why don't I do the same thing with my Toastmaster speeches? That would help me understand, quantitatively, what words I "rely on" the most and help me think about how I might vary my language to make my speeches more accurately express the meanings I intend to. 

So off I went. I located my Toastmaster Icebreaker speech (I had typed  it up in a Word document), started MATLAB, and began fiddling at the command line.

So I can't read a Word document?

Being an infrequent user of MATLAB's file processing functionality, I wasn't sure what function read Word documents. I searched "read Word document MATLAB" on Google. The highest ranked hit was How to read MS Word file in MATLAB, a discussion thread pointing out that MATLAB does not have built-in function for reading Word documents. An alternative suggested by the thread was to use a MATLAB Central File Exchange submission from the MATLAB user community targeting Word documents. Downloading the submission and figuring out how to use it sounded like more trouble than I wanted. I wanted a quicker and simpler solution.

The simplest text format I can think of is plain text. MATLAB must work with plain text out of the box. So I searched for "read text MATLAB" and found the textread function.  It seemed to be what I wanted. I gave it a try and sure enough, it worked.

Mishap with Google's first ranked choice: textsread vs. textscan

But interestingly, textread, from Google's top ranked page that matched my search,  is not a recommended function (See figure below). Instead, textscan is recommended. The choice of name "scan" sounded awfully mechanical to me. It was a machine-centric word. As a human, I "read" a file, never "scan" it unless I really meant to briefly check it out. Here was a prominent mismatch between how a user expressed what she wanted the computer to do (to "read") and how an API 's name missed that by reflecting what the computer did (to "scan").

Apart from being surprised at the name of the recommended API, I wanted to know why textread was not recommend or why textcan was recommended. I couldn't find an answer. I couldn't find it on the doc page of textread or the doc page of textscan. I was left unsure about the implications of my choice with textread.

More choices if you will…

To make things more confusing, I discovered more functions that seemed to be operating in the proximity of text reading (See figures blow for functions shown in the See Also section of both pages). Now, I was ready to give up on trying to understand the differences amongst all these functions. It was too much to figure out for a simple task I wanted to do. Just read my file!

The final choice

In the end, I stayed with textread, the first seemingly working function Google led me to. I suspects this might be the choice of many users first coming to MATLAB's file reading functionality would choose. It matches the user's language and was ranked highest by Google which is arguably the most frequent way a user finds his/her way into an unfamiliar MATLAB function.

What went wrong and what could've helped?

Computer did not having a matching feature for users' file type.

I had my speech written up in a Word document so I wanted to read it. It was only when I discovered that MATLAB didn't not have that built-in functionality to read a Word document did I resort to text.

Suggestion: Having functions that match users' needs. The current functions that operate on text is very low level. Many users do not work with plain text files.

Computer did not speak user's language.

I wanted to "read" my file which led me to textread. However, the recommended function was textscan, a name I would not have guessed.

Suggestion: Name the APIs better so that they match users' language.

Computer provided multiple choices without giving information on the implications for going with each

I couldn't find the explanations on why textscan was recommended over textread. Furthermore, the See Also section showed more options which overwhelmed me.

Suggestion: Help users select an API by showing them the differences between the different choices and implications for their choice. I was almost thinking the side-by-side comparison chart that are common on many consumer product sites like this one from Vitacost for helping a user select a multivitamin. Why should API selection be any harder?