Presentation outline

1. Product overviews 2. Get started tutorials
a. Best practices a. Best practices
b. Examples b. Examples
c. Reasons for failure c. Reasons for failure

Slides are online here: idbwrtng.com/wdcb

Best practices for overviews

  • Description of the product
  • Sample use cases
  • Intended audience and level
  • Requirements for use
  • List of components involved
  • High-level workflow
  • Development effort and scope
  • How to get support
  • Known limitations
  • Link to getting started tutorial

Product overview examples

  1. IBM Watson Assistant
  2. AWS Lambda
  3. RingCentral
  4. Ably
  5. Anomaly Detector
  6. Alexa Video Skills Kit

Which site does the best job with product overviews? Why?

Slide link: idbwrtng.com/wdcb1

Reasons for poor product overviews

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

read more »

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

read more »

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

read more »

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

read more »

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

read more »

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

read more »

Best practices for getting started

  • Link from the homepage
  • Include sufficient product detail
  • Let users taste success
  • Remove setup burdens
  • Take a user from A to Z
  • Link copiously to other topics
  • Welcome teaching moments
  • Make sure the tutorial works
  • Include troubleshooting tips
  • Also use for internal testing

Getting started examples

  1. SendGrid
  2. PayPal
  3. PlatformOS
  4. Deutsche Bank
  5. Fedex
  6. Azure Anomaly Detector

Which site does the best job with getting started? Why?

Slide link: idbwrtng.com/wdcb2

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

read more »

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

read more »

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

read more »

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

read more »

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

read more »

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

read more »

Balancing the two

Intersections

Linking, cross-referencing, springboarding between the two

More reading

Contact