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.
- User research
- Information architecture
- UX design
- Front-end development
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 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.
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.
The research led us to several key design principles.
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.
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.
Lessons and Next Steps
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.