August 28th, 2023

Show Me, Don't Tell Me

In my time as an engineer I’ve reviewed (and will review) tons of engineering proposals. So far these proposals have ranged from small changes in infrastructure or code all the way to extensive architectural proposals that could span years to reach completion. In all of those proposals there’s a single factor that separates a good or poor proposal from a great proposal: They “show me”, not “tell me”.

What it means to “Show me”

While documents and proposals are often abstract and create a blurry picture, proof-of-concepts, demos, example Pull Requests, and other forms of “Show me” are meant to create more clarity and direct conversation. By actively proving instead of strictly trying to convince, you benefit from:

  • Your proposal has been proved realistic to a certain extent or you have failed fast and can go back to the drawing board.
  • An entire class of questions around theoretical concerns and misunderstandings can be clarified by sharing the proof-of-concept/demo.
  • You’ll likely discover some hidden roadblocks and blockers that may require your proposal to change or provide valuable context worth documenting.
  • The staffing requirements and level of effort is much more clear.
  • You’ve created an artifact that others can take and “Show you” (often in the form of a yes and) which can lead to more collaboration and better outcomes.

These benefits instill confidence and eliminate some amount of FUD. This can create significantly more support for your ideas because it makes it much easier for folks to point at your “Show me” and say “we proved these goals are achievable”.

Here’s a few examples of where you could use a “Show me” to get some of the benefits outlined above:

Are you proposing adopting a new database technology? Find a simple use-case, implement it, and show me the code, metrics, performance, etc.

Do you have a brilliant idea for a new API that can solve a critical problem plaguing your system? Find the top 3 offenders and fix them with this new API.

Breaking apart a large, tangled system? Find an example subsystem, break it apart, and ship it.

Why don’t more folks “Show me”?

Depending on who you ask the answer to this question might be charitable, or it could be getting into spicy take territory. Personally I think my opinion is somewhere in the middle:

It’s hard.

Don’t get me wrong, thinking and coming up with solutions is hard too but the value in the proposal isn’t the idea or the words, but the end outcome. This is why I find it so important to “Show me”. Without the proof, we’re often stuck arguing about the theoretical benefits and downsides of a solution when we could be grounding the discussion in reality.

Show me, Don’t Tell Me

If all of this boils down to a single takeaway I think it’s this: It’s often easier to prove than it is to convince, and you can’t convince everyone.