Writing It Up

A case study is not a feature list. It is the story of a problem and the decisions you made about it.

The problem and who has it. What you built. Two or three decisions you actually agonized over, with the alternative you rejected and why. What went wrong and what you did. What you would do differently. What you learned that you did not expect.

The rejected alternative is the part that makes it credible. Anybody can list what they chose; describing what you chose against shows there was a decision.

✦ Be specific, and be honest about limits

'It handles errors well' means nothing. 'A failed search shows a retry and keeps the query, because losing what they typed was the most annoying thing in my first version' is a sentence somebody believes. The same applies to limits: naming what your application does not do makes everything else more credible, exactly as it did in APIs & Datasets.