why documentation quality affects reviews

For code-based digital products, the quality of your documentation directly predicts your review score. A buyer who can't get the product working leaves a 1-star review. A buyer with a clear setup guide leaves a 5-star review saying "everything worked first try."

the four-section structure

# product name

## what's included
Brief list of every file and its purpose.

## quick start
Three to five steps. Numbered. No jargon.

## reference
Detailed notes on each file, variable, or option.

## troubleshooting
The 3-5 most common issues and their solutions.

writing the quick start

Assume the reader has installed the product and is staring at the files with no idea what to do. What do they open first? What do they paste where? What should they see when it works? Write those three things — nothing else — in the quick start section.

markdown best practices

  • Use backticks for file names, code, and settings: `free-shipping-progress.liquid`
  • Use numbered lists for ordered steps; bullet lists for unordered options
  • Use horizontal rules (---) to separate major sections visually
  • Never use nested headers deeper than h3 — buyers don't read deeply nested docs

keeping docs up to date

Every product update should come with a documentation review. The most common 1-star review for code products: "the instructions are outdated." Pin a version number (v1.2) in the doc header and update it with every substantive change.