I’ve always had a a touch of impatience when it comes to programming. Done is better than perfect. The programming stacks I choose reflect this. It’s for this reason I often get frustrated with documentation. The most important parts of documentation often lack clean entry points. Like a method signature that expects a dozen parameters, the most critical documentation is difficult to decipher.

RTFM is less about reading the documentation, and more about slowing down to breathe. Don’t expect all interfaces to be delivered on a silver, perfectly organized platter.

Take for example my favorite server-side framework, Rails. I am comfortable with Rails because I’ve been working with it for 8 years. I know most of the nooks and crannies. But I also know that Rails can be tough to get up to speed with. “The sugar is too sweet. I don’t know what’s going on,” a friend once said.

This is because most documentation fails at being a bridge. We have getting started guides and we have full-blown documentation, but we do not have a bridge in between the two. Although Rails is simple, the road from being a beginner to an expert was paved almost entirely by one man: Ryan Bates. Mr. Bates developed Railscasts and kept going. After nearly 500 episodes, he stopped.

This is why we built Sandbox at imgix, it serves as a REPL and an effective bridge between our guides and docs. It’s a safe place to fail.

Good documentation has the pieces of this: Stripe’s documentation fills in your tokens when you browse the docs. The Go language has a playground. Swift also has a Playgrounds feature.

Although I barely passed my screenwriting class in film school, I do remember that the professor stressed that, “Poor writers always tell the reader about the scene, great writers show.” Given that this is a blog post on the internet, it’s my moral duty to extrapolate and generalize anecdotal evidence into a compelling narrative. Anything for you, dear reader. Poor documentation merely lays out the technical specs and details of an interface and stops there. Good documentation shows the interface in action. Great documentation lets the user play without consequence.

Although it’s technically quite simple, I like the work that we’ve done with Sandbox. It smooths the path in programming that I like the most: going from zero to one. Going from confused to “I get it.” The proverbial light bulb.

This isn’t to say the the exhaustive documentation is not useful, it’s rather to say that that is the expert mode of our service. We do not expect those just learning about imgix to instantly dive into the docs.

The smartest companies understand the importance of this first taste for the customer. Some do it through fake data set up with each new account. Others do it with

The next time you’re at work and deciding how to lay out the documentation for your service, take the three-pronged approach:

• Establish a set of guides to whet the appetite
• Build out a comprehensive set of docs that detail every detail of your service
• Build a interactive bridge between the two

This smooths the path for potential customers. The easier you make it to know very little about your service to become an expert, the better. For some companies, there is no upper bound to knowledge. (There are people outside of Microsoft and Adobe that know more about Excel and Photoshop, respectively.)

Show, don’t tell. And when you can, play.