In order to understand the problems faced by first-time learners of API documentation, I had to conduct some user research. I went about this by collecting it in a few different ways:

Contextual Inquiry

 

A contextual inquiry is where you observe the tools used, the sequences followed, and methods used by a user to solve a problem.

1. My first session along these lines was an interview and walkthrough with someone who regularly trains employees on how to document API's. I cannot reveal what this person said or showed me, but, from this observation and conversation, I gained insight into how people thought about API docs, the emotions felt by first-time learners, and learned some of the terminology used in the field.

 

 

2. My second contextual inquiry was observing someone who had almost no exposure to API documentation as they searched the web for 20 minutes trying to teach it to themselves as fast as possible. It was interesting to see what they found based on Google searches, how they scanned the information, and what frustrated them.

Write the Docs on Slack

 

On the Write The Docs Slack (an organization made up of technical writers who work on developer documentation) channel, I asked about people's first-time experiences writing API docs. I garnered several responses and stories, but most people provided only the technical details. I tried to ask follow-up questions about how they felt at the time, how difficult it was, what their learning environment was, etc. But, I got very little information on that front.

For me, this was a reminder that API doc writers might lean toward the technical side, excited to talk about tools, and not be used to discussing things in terms of feelings or user experience.

Email
 

I emailed a few professional connections, to get their take on their experience learning API docs, and teaching it, to no avail. I got a few references, email addresses, to appropriate people, but ultimately didn't hear back. I definitely learned that people with this skillset are very busy!