Case studies
How to write up a BSV product you worked on, and what makes one worth reading.
The rest of this guide is advice. A case study is evidence.
If you have shipped a BSV wallet, an app that connects to one, or anything that asks people to spend satoshis, the hard parts are what this guide cannot derive from the standards. Writing them up is the most valuable contribution there is.
Why this section matters here
We know of little published work on paying per request, on permission screens, or on designing around a payment that cannot be reversed once accepted. The guide can reason about those. It cannot tell you what happened when real people met them.
What makes one worth reading
Do
Write about one problem. A case study that covers a whole product covers nothing.
Do
Include what did not work. The failed version is the half that teaches something, and it is the half everyone leaves out.
Do
Put numbers in where you have them. Completion rate, support volume, how many people got stuck at which step.
Don't
Write a launch announcement. If the piece has no moment where you were wrong, it is marketing.
Aim for the length of a long page, not a report. Readers scan for the insight, so give them headings to scan.
A structure that works
This is not a template, and you need not keep the order. Each part is here because readers look for it.
How it started
The problem, and how it surfaced. Who was in the team. Enough about the product that the rest makes sense.
Show: the final design, up front. Readers decide whether to keep going by whether the result looks worth the journey.
Who it is for
The people the product is built for, and how you know. If you did not know at the start and had to find out, that is the more useful story.
See User personas for four worked examples and the format they use.
What you did
The steps that produced the insight, not every step. Where you got stuck, what you changed your mind about, which tool helped.
Show: flows, annotated screens, research notes. These can be messy. Messy artefacts are more convincing than tidy ones.
What you learned
Turn each finding into something another team could act on. A finding phrased as an instruction is worth five phrased as observations.
What happened next
Did it ship? What changed afterwards, in numbers if you have them and impressions if you do not? What is still unsolved?
Sources and thanks
The design file, the research, the repository. And the people, named.
The things this guide most wants written up
If you are deciding what to write about, these are the gaps:
- A permission screen that worked. What you asked for, what people granted, what they refused.
- Pay-per-use in a real product. How you showed hundreds of tiny payments without making people anxious.
- Recovery, measured. How many people could actually restore a wallet, and what the failures had in common.
- A handle rollout. What people understood a handle to be, and what they called it.
- Something irreversible going wrong. How you told the user, and what they did next.
- A pricing change. What you charged per use, what you changed it to, and what happened.
- An agent with a budget in production. What limits people set, and what they did when the agent hit one.
How to submit one
Write it as a markdown page under content/guide/case-studies/ and open a pull request. See Propose a change and Formatting.
If you would rather talk it through before writing, say so through the enquiry form.
Recommendation
Do not wait until the work is finished or the result is good. A case study about a thing that half worked is more useful than one about a success, and far more rare.
Related
Written from: docs/DOCS-PLAN.md.
Checklist
The rules on this page, in a form you can work through.
5 rules