“You never get a second chance to make a first impression”: writing great “getting started” documentation¶
Description
As the old saying goes, “you never get a second chance to make a first impression”. When you first meet someone new (not least at a conference for documentarians!), those first few moments set the tone. In exactly the same way, the experience your user has when they first “meet” your product and get to grips with it will set the tone for your entire relationship with them.
As documentarians, we so often focus on building detailed and exhaustive “reference” documentation, but in doing that, we forget to provide the right kind of “getting started” experience for a user brand new to our product.
At GoCardless, we spent the first years of the life of our platform focused on building high-quality reference documentation. But in Summer 2016, we kicked off a big piece of work on a new set of resources: a “getting started” guide for our API, getting the user from nought-to-sixty on our developer platform.
To make the right first impression, we had to turn things on their head and think from the reader’s perspective. From this perspective, what we’ll write and build looks very different to our “reference” documentation, seeking not only to teach the user how to use our product, but also to explain the fundamental concepts behind it and to bring the user to the all-important “aha!” moment where they see the value in what we’re offering.
In this talk, I’ll go through:
the fundamental differences between “reference” and “getting started” documentation
the lessons we learnt on the way as we experimented and spent extensive time with end users
what we built
the results — from our users’ perspective, and in terms of how we build demand within the company for further “getting started” content
- Conference: Write the Docs EU
- Year: 2017
About the speaker
