I’m getting ready to make a bunch of pies. And, yep, this does have something to do with documentation.

In the US, Thanksgiving is coming up in a few weeks. I’ll be getting out Grandma’s old pie crust recipe and rolling my way through the dessert course.

The recipe makes a bold promise: “No Fail”

These pies get compliments. Among my favorite things, though, are the parenthetical clarifications throughout the recipe.

Right at the end is a hand-written note: “5 cups flour works best (less rich)”

It’s one thing to share the steps to follow. It’s quite another to explain why.

That second part is often missing from these sorts of family traditions. Like the apocryphal story of the cut ham:

A child, watching a parent prepare dinner, asks why they trim the edges off the ham before they put it in the pan. “It’s how my parents did it.” The child won’t let that answer pass. After a few questions through the family tree, they found out that a great-grandparent had a pan that was too small for the whole ham. And that’s why they trim the edges off the ham, generations later.

Instructions get passed down and not always with the full context.

Those parenthetical comments in the pie crust recipe make me think my grandma could have written some good developer docs…

Documentation that only explains how something works misses an opportunity to pass on important knowledge. That’s why use cases are so important—they fill in the details about why your product matters.

Even though use case pages might appear like flashy marketing, the best ones also inspire technical audiences. When you can imagine solutions to common problems, it’s much easier to see how a product would also solve your own technical problem.

​Reach out to EveryDeveloper to get an objective look at your use cases—and ensure there’s a consistent narrative all the way through your documentation.