This talk idea comes from a problem that I’ve noticed in the API documentation community: tutorials that skip important details, lead to scary error messages, and fail to direct readers to additional resources like onboarding and documentation. Flawed tutorials like these get published due to the “curse of expertise”: the people who write API tutorials tend to be intimately familiar with an API – perhaps they even coded it themselves – whereas the people who read API tutorials may be experiencing that API for the first time.

Thus, in most API communities, there is a chasm between the tutorial writer’s and reader’s knowledge of a given API. This knowledge gap often leads to the scenario in which the reader gets frustrated in the midst of reading a tutorial because the writer made assumptions about the reader’s knowledge of an API. These assumptions can lead to the aforementioned problems that prevent a reader from moving onward in a tutorial. These assumptions cause readers – potential API users – to leave an API for good.

It can be difficult for a writer who is experienced with their API to think like a beginner as they write their tutorial, but it is so important for them to write accessible API tutorials in order to retain new API users and bolster their evangelism efforts. How well API tutorials cater to beginners will make or break that API’s developer community.

In this talk, I will share techniques that top technical writers use to ensure that their tutorials are easy to follow for coding beginners, and how these translate to a framework that API documentation writers can employ to write tutorials that are comprehensible to new API users. After my talk is over, I’d like the audience to incorporate this proofreading framework into their API tutorial-writing workflow.