Writing documentation is a valuable way to gain insight into the usability of APIs or software interfaces. This holds especially true for small teams, since it has low overhead.
The Chore of Documentation
Often times when writing software, documentation is written at the end of the process. The software has gone through iterations of development and design, and all that remains is documentation. All too often this involves throwing together some instructions for use, or auto-generating API docs. In my experience, this approach misses a great opportunity to improve the usability of a project.
Usability Testing
The traditional approach to improving the usability of software is to do usability testing. This is an amazingly beneficial process where you get insight from actual users as they try to use the software. The downsides to this approach include that the product needs to be in a usable state, and requires the overhead of finding users and setting up the testing scenario/environment.
Usability Inspection
In contrast to usability testing, usability inspection is a group of methods to evaluate usability without involving users or a functional product. A prototype, or even an API outline, can be sufficient material to work with. A cognitive walkthrough is a task-based method, asking questions about a user’s interactions as they try to achieve a task.
Documentation for Usability Sake
As I’ve worked on documentation for various software libraries, frameworks, websites and applications over the years, I’ve grown to find that the process of writing documentation can be a valuable tool in improving the usability of a project.
Typically documentation is seen as a method to teach the user how to accomplish as task, or to show them what options they have. However, I believe it is actually rather helpful for a product team to identify unnecessary complexity, inconsistency or unintuitive behavior. It ends up being similar to the cognitive walkthrough mentioned earlier.
In the process of writing the documentation, the authors should note areas where concepts are complicated to explain, or where statements have to be extensively qualified. Such complexity in the documentation exposes a complexity inherent in the software itself.
Ideally the insight from the documentation process is then fed back into the product iterations. This is an inexpensive way, with almost no overhead, to improve usability.
Obviously larger teams will tend to have more resources to integrate user testing into their projects, but even single-person open source projects can benefit from the process of writing documentation.
One nice side effect is having useful docs created along the way!