Daniel D. Beck

Documentation is artificial experience

When presented with some device or software, a new user needs to answer some fundamental questions like, What is this thing?, What is it good for?, and How do I use it? Perhaps the plainest way to answer those questions is through real, lived experience, such as direct examination or experimentation. Given a physical device, for instance, a user can answer those questions by turning it over in her hands, locating physical features, or playing with the device, pushing buttons and flipping switches.

The other way to answer those questions is by consuming the documentation. Documentation isn’t the same as experience, but provides a quality of user experience which approaches the real thing. Documentation affords new users the abilities of a more experienced user, with lower costs than gaining all of the experience directly, as through experimentation and practice. Those costs include time spent learning, the frustrations of the gulf between desire and ability, and others. How much and what kinds of experience documentation successfully substitutes is a handy lens through which to evaluate documentation and make choices about documentation goals.

The most basic form of documentation answers those early questions (What is this thing?) which make up a user’s earliest experience with the thing documented. Given a physical device, for instance, basic documentation allows a user to skip much of the preliminary experience of turning it over in her hands and locating all of the physical features that identify the object. Product packaging, by identifying the product for would-be owners, serves as a kind of basic documentation in many cases (indeed, many products are sold such that the packaging is the only documentation).

Common documentation identifies a thing and describes its usual functions, like turning on, setting up, and major, advertised features. It often takes the form of an instruction booklet, a README file, or a quick start guide. While helpful, such documentation represents the kind of experience which can be recreated in isolation by a sufficiently eager new user. Such documentation does not provide any information about the software or device’s place in the world.

Great documentation goes beyond mere identification or cursory functional capability. Great documentation contextualizes the documented thing and enables non-trivial accomplishments, composition with other tools, and critical thinking about the documentation’s subject. This kind of documentation gives the audience a substitute to experience they would not necessarily attain on their own, as the experience is non-obvious, developed over a long period of time, or must be attained outside the audience’s immediate context. In the model of documentation as substitute experience, great documentation helps a user understand how the thing documented relates to her life and how it can be used to solve her problems.

One of my favorite examples of this kind of documentation is the SQLite documentation page, Appropriate Uses For SQLite. SQLite is a software library that provides a single file, serverless SQL database. A serverless SQL database is an odd thing and unlike high-profile databases like MySQL in important ways. Less sophisticated documentation might describe how to use the database and call it a day, but Appropriate Uses for SQLite is a bit smarter:

A screenshot of the Appropriate Uses for SQLite doc

The page’s first section, Situations Where SQLite Works Well, describes applications where SQLite has succeeded. It’s not a list of available features. Rather, it’s a list of scenarios in which SQLite is thought to be a suitable database candidate: application file formats, low-traffic websites, prototyping, testing, and teaching, to name a few. But where the page really shines is in the subsequent section, Situations Where Another RDBMS May Work Better. That section describes scenarios in which SQLite would make an ill-advised database choice.

By the inclusion of those two sections, the SQLite documentation helps the audience to make smarter decisions about when and how to use SQLite. By abbreviating the process of learning to make choices with SQLite, the documentation enables the audience to accomplish their goals, not just complete a set of procedures which are limited to the software in isolation.

So the next time you’re thinking about the scope of your documentation, take a look at Appropriate Uses For SQLite and ask yourself, How can I give my audience a shortcut to experience?