jINQUIRY: REDESIGNING DOCUMENTATION

How might we make technical references user-centric in this digital world?

 

As digital tools increase in number and in complexity, the reference documentation for these tools is falling far behind in readability and usability. I collaborated with Ritwik Deshpande to kickstart a long-term project to test different approaches for reimagining a more user-friendly documentation framework. We built our first prototype, jInquiry, with a dynamic showcase panel within two weeks.

SCOPE

3 weeks

CATEGORIES
  • User research
  • Information architecture
  • UX design
  • Front-end development
ROLE

Designed and deployed prototype site, pair-coded it in Javascript with Ritwik.

COLLABORATORS

Ritwik Deshpande

 
 

The Problem

API documentation is unintuitive for the non-expert programmer.

The universe of digital tools out there today is exploding: everyday there are new products, new code libraries, new APIs. A growing proportion of these tools are technically complex as the number of tech-savvy people out there grows. As tools get more advanced, their reference manuals — the documentation — is failing to keep up. The documentation is either non-existent, or is tailored to the hardcore programmer: text-heavy, full of jargon, and difficult to navigate. At the same time, more people are picking up programming, and are getting disheartened when they encounter unreadable technical references.

The current state of jQuery documentation. We've highlighted problem spaces in the callout boxes.

The current state of jQuery documentation. We've highlighted problem spaces in the callout boxes.

The frustration can often be found in pleas for help within coding forums, such as within the comments in the following Stack Overflow question:

"It's often not easy to make sense of documentation at first. Why is API documentation written in such a way as to confuse perennial newbs / hackers / DIYers like myself?"

— Stack Overflow user dbonneville

Although this began as a final project for a code assignment, Ritwik and I have made it our long term goal to iterate on prototypes for better technical documentation. For our first prototype, we decided to tackle the jQuery’s API documentation since the main target audience of this documentation is a community of visually-inclined programmers who might appreciate our redesign. We decided to start with a single method in the API — the .fadeOut method.


The Process

We evaluated the landscape of existing technical references, and crafted the key principles to guide our design.

Ritwik and I have always been interested in code literacy: we have worked on several projects together on this subject. This project was born out of our own frustrations with the technical documentation that we encounter daily.

We began by evaluating the current state of jQuery documentation, doing a thorough heuristic evaluation of the site and its contents. We then interviewed existing users to find out what their frustrations were with the documentation.

We also researched the landscape. We spoke to seasoned programmers, and studied the documentation that they recommended. There were a few technical documentations that demonstrated innovative ways to convey information. We found that documentation that showed users step-by-step visual feedback, as well the ones that encouraged participation, generally felt more effective.

Documentation for P5.js.

Documentation for P5.js.

The research led us to several key design principles.

Identifying problem statements and crafting design principles

Identifying problem statements and crafting design principles


The Design

jInquiry is an interactive framework that dynamically generates the correct way to write the code and provides a demo of the code in action.

We designed jInquiry, an interactive framework for demonstrating all the capabilities of a single jQuery method. Just like a traditional API reference, it shows all the necessary information about the method, such as the arguments it takes and the possible values and datatypes for each argument. Beyond that, it also quickly demonstrates the syntax in which to write the method, and showcases the selected code in action to give users a clearer idea of the results of the code.

 
 

The jInquiry interface has three regions: the argument selection column, the syntax display, and the showcase. First, there is a list of arguments that users can select to include in the method. Second, a large display of the fadeOut method sits in the top banner and changes dynamically as users select the arguments, demonstrating the proper syntax. Third, a showcase panel at the bottom right demonstrates the resulting jQuery animation in real time, taking in inputs that the user has entered.

The dynamic syntax display in the top banner.

The dynamic syntax display in the top banner.

Our prototype also keeps the navigation tucked away in a sliding drawer menu. This gives us room to fill the full page with the UI for learning about the particular method, instead of being distracted by all the other parts of the jQuery library.

The sliding drawer menu.

The sliding drawer menu.

Hover tips provide more information about the data type of each argument.

Hover tips provide more information about the data type of each argument.


Lessons and Next Steps

The number one thing we took away from this exercise was how complex APIs can be.

The fadeOut jQuery method alone has different syntaxes, each with different arguments, and each argument can take a range of inputs. It was a great challenge thinking through how to display all of this information in a digestible manner.

We are currently prototyping other variations of documentation: our prototype will focus on making annotations in-line within sample code. The next steps would be to put these prototypes in front of both beginning-intermediate programmers, as well as existing advanced coders, for user testing and feedback.