Product overviews vs. getting started tutorials

striking a balance between read-first and try-first user behaviors

By Tom Johnson / @tomjohnson
idratherbewriting.com

Slides available at
idratherbewriting.com/slides/overviews_and_tutorials.html

Experiences with product overviews and getting started tutorials

Best practices for overviews

  • Description of the product
  • Sample use cases
  • Intended audience and technical level
  • Requirements for use (system requirements, geo-requirements)
  • List of components involved

Best practices (cont.)

  • Architectural diagram of components
  • High-level workflow
  • Development effort and scope
  • How to get support
  • Most popular topics
  • Known limitations, release notes
  • Link to getting started tutorial

Reasons for poor product overviews

Cause 1: The reader isn't the intended audience, so the overview fails for the reader

Cause 2: UX's influence on intuitiveness implies that long overviews indicate bad design

Cause 3: Overview pages are hard to write, so they’re often neglected

Cause 4: Agile's co-development influence makes it difficult to surface higher-level content needs

Cause 5: Higher-level content is already handled by developer marketing content, making it redundant in docs

Cause 6: Tech comm buys in to the "reading to do" paradigm for docs, reducing the value of longer conceptual docs

Getting started best practices

  • Allow a new user to have some success with your product, even if small
  • Remove the burden about setup requirements as much as possible
  • Take a user from beginning to end through the tutorial

Best practices (cont.)

  • Make sure the tutorial actually works and provides the advertised result
  • Take the opportunity for teaching moments and asides during the tutorial
  • Include a troubleshooting section that covers common issues

Reasons for poor GS tutorials

Cause 1: Getting started tutorials are seen as an optional extra, and few writers have time for optional work at release crunch times

Cause 2: The product setup might be too involved or impractical for a getting started tutorial

Cause 3: There’s no sample app to demonstrate how to call the API

Cause 4: The getting started tutorial omits details for the sake of brevity, which threatens clarity

Cause 5: The tech might be too complicated for tech writers to walk through themselves

Cause 6: The content isn't tested against real users

Balancing the two

Linking, cross-referencing, spring-boarding between the two

More reading

Contact