The Trick to Documenting & Explaining Any Complicated Tech Process

You ever find yourself trying to explain something technical to someone, and feeling as if you’re speaking another language?

Good. So it’s not just me.

Being in a technical role, and the only person who understands some parts of that tech, means I get the job of explaining to people why things work the way they do. I’m a nerd about bringing people into my work, so I’m happy to do it.

But sometimes, the tech realities are dense. That means the explanation can be long and complicated to wrap your head around….which includes me. Not to mention, the person on the other side may find it all boring! 🤔

That’s why I’m excited about using this technique more in my work, especially when it comes to documenting that tough stuff.

Enter Database Ad-libs.

You know that game with the sentences,where you fill in the blanks? As it turns out, that simple game is also the basis for a highly sophisticated documentation model!

Our ad-libs game looks like this:

When this __ real life event __ happens, then this ___resulting real life event___ happens, by way of this _____technical mechanism____ , which does this/these _____technical things)____.

If that sounds easy, it’s not. BUT it’s a good starting point to simplify what might otherwise be a pain in the butt to describe.

Let’s use this model to document a common nonprofit marketing process: donor acknowledgments.

In Salesforce, we store individual personal data in Contact records. Within that, we can have different types of contacts – like Volunteers, Students, and other program constituents.

Let’s say that whenever a volunteer makes a donation, we need to add them to a special list that kicks off a series of automated, custom thank-you emails. How can we document that in a way that makes sense?

Using the ad-libs model and the BEST Word feature on earth: tables.

In this table, the first two columns describe actions taking place in the literal world. The last two columns describe the technical things happening in the database.

Now, this example only describes one subset of a larger process. We’re serious admins here. So let’s expand and document the different criterion that impacts our acknowledgment process.

Here’s our new ad-libs model, times 100.

Note the new “and also” second column. Depending on how complex you want to get, add columns to highlight specific criteria!

If you can document it, you can be it.

I know gang, it’s cheesy! But if you can write it, then you can explain it. And if you can explain something in a way that makes the non-technical person follow along, then you’ve basically won the database games.

Liked what you read? Spread the word!

Share your thoughts!