Wearing my Reebok Pumps and Starter jacket, I was trying way too hard to be cool. Strange to think I was learning an important lesson about documentation before my 12th birthday.

It was early in the school year and each student was answering a personal questionnaire. You know the type: favorite ice cream, musical artist, vacation spot.

I diligently filled mine out with my cohort at table three, the whole room silent. Then came word from the front of the class that we must exchange papers and introduce one another.

Public speaking is part of my repertoire now (in fact, catch my talk at apidays this week), but it’s uncomfortable for most youngsters. I was no different. Thankfully, my partner’s answers looked easy enough—plus, I’d known him since kindergarten.

I rose from my seat and read from his paper:

• This is Mike
• He likes vanilla ice cream
• His favorite music is MC Hammer
• He went to Disneyland

​
As quickly as I could, I fell to my seat, glad my public humiliation was over. Alas, Mike had other plans…

“This is Adam. This summer he walked along the Grand Canyon holding hands with Paula Abdul. At night they stared into each other’s eyes while eating peppermint ice cream.”

I was mortified at the liberties he’d taken with my answers. At our age, it was embarrassing to suggest someone had a girlfriend. Even worse, Mike had tapped into what was probably my dream.

Here’s the thing: he also tapped into an important lesson that’s still part of my work today. The introduction I read was a boring list of facts. Mike helped the class see how those facts worked together. Granted, it was inaccurate, but it was a heckuva lot more interesting.

In your documentation, there’s a place for a list of facts, like a reference. Docs need to go beyond what your product does. You need to tell developers why it matters. Help them see how the pieces fit together. Good documentation examples share use cases, explain edge cases, and provide code snippets.

You can Paula Abdul your docs and help the developers that find them be more successful. There’s more about this approach in my book (though no additional Paula Abdul stories, sadly). You can also reach out to Every Developer if you need assistance.