WriteTheDocs 2017 – You never get a second chance to make first impression

Speaker: Tim Rogers

Writing great "getting started" documentation

Tim started out with a reference documentation (comprehensive and up to date) and a few blog posts to go along with it. And still people asked how to get started, and how to do the most simple things. Since documentarians are meant to be advocates for users, and find out what leads to users struggling.

Questions

  1. Who am I writing for? What do they want to achieve? What are their goals and struggles? (Personas, user groups, use cases, etc – you can keep segmenting more and more later on)
  2. What do I want to tell them about? (Bring them to the Magic Moment/Eureka Moment/…, showing the value the product supplies. Users who maintain magic moments will stay much longer with the product.)

"Getting started" documentation is very much required.

Reference docs are not enough

Look, for example, at the stripe docs, or clearbit docs which interactively take you to the code samples you need, including your API key. The twilio docs are great aswell.

Build a linear experience for in your guides

  1. Introduce key concepts: Not all of them, naturally, and introduce them gradually where and when needed.
  2. Hand-holding through first steps: Make your user feel safe by making them feel like they understand the system
  3. End with a summary, and a link to the next section.
  4. Include best practices both as concepts and by example.
  5. Test with real beginners.
  6. Integrate your docs with your product: Offer links to documentation a lot, embedded as first-class citizens
  7. Simplify aggressively

Also, do not neglect your reference docs but accept that users have different needs. And don't forget that your docs are incomplete without a Getting Started guide.