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: /overviews_and_tutorialsv2.html

Best practices for overviews

Product overview examples

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

Slide link: overviews_and_tutorialsv2.html#/3

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

Best practices for getting started

Getting started examples

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

Slide link: overviews_and_tutorialsv2.html#/6

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

Intersections

Linking, cross-referencing, springboarding between the two

More reading

Contact

Tom Johnson
— idratherbewriting.com
— @tomjohnson
— [email protected]