Pathwise

Manuals / Writing Better Documentation / Chapter 2

Craft · beginner · ~35 min · Chapter 2 of 3

Example first

Show the happy path command or snippet before the theory.

Path progress
67%

Step 1 of 1

Copy-pasteable wins

If someone can’t paste and succeed, the doc failed. Include expected output.

Copy-pasteable winsDrag stickies · tap for tips
Study mapDrag stickies · tap for tipsKeep it shortdrag · tap →Name the waitdrag · tap →Scope locatorsdrag · tap →Trace when stuckdrag · tap →One browser firstdrag · tap →Isolate statedrag · tap →Assert the UIdrag · tap →Retry wiselydrag · tap →Seed datadrag · tap →Close the loopdrag · tap →Keep it shortdrag · tap →Name the waitdrag · tap →Scope locatorsdrag · tap →Trace when stuckdrag · tap →One browser firstdrag · tap →Isolate statedrag · tap →Pathwise hackdrag · tap →Copy-pasteable windrag · tap →Try thisdrag · tap →Follow the dashed drag · tap →

Try it

How-to skeleton

## Goal
## Prerequisites
## Steps
## Expected result
## If it fails

Do this now

Rewrite one paragraph as numbered steps + expected result.

Was this step clear?
Chapter learning outcomes
  • Examples
  • Failure modes

Clear these before you leave