A Tech Explainer’s Pledge

I like helping people learn things that they weren’t sure they could understand. In tech culture, there sure is a lot of bluster, buzzwords and hand-waving. This is a pledge that I am making to myself and you to keep myself honest.

  1. I will always define terms using nouns, not verbs.
    1. It’s helpful to say “Blob.ly is a for-pay website that lets people store and retrieve big files.” It’s not helpful to say “Legu.me is a better way to find lentil soup recipes.”
  2. I will never define something as a “solution“, “platform“, or “framework“.
    1. Defining a thing as a  “solution” is the same as defining it with a verb. When you say “Legu.me is an enterprise recipe solution”, it’s the same as saying “Legu.me solves a recipe problem for enterprises, but I’m going to be coquettish about what recipe problem it solves, on what scale, and what we mean by enterprise.” Similarly, “platform” and “framework” are too general to be helpful.
  3. I will define all buzzwords and expand all acronyms.
    1. No alphabet soup without definitions! There are so many acronyms that overlap even within one field, that expanding an acronym once per article (as in academic and news articles) is almost always appropriate.
  4. Be honest about bluster.
    1. When I don’t understand something, I will say so. I will listen to my spidey sense to help me figure out whether it’s because I haven’t learned enough, because the documentation is lackluster, or because someone has gone out of their way to make it seem complicated and out of reach.
  5. Strive for plain language definitions.
    1. Years ago, when SAN (storage area network) systems were relatively new, I struggled a lot trying to understand them. They seemed like they should be pretty straightforward and adhere to basic principles of disks and networking, but the lived reality was that setting them up was a tangle of weird, flaky protocols and delicate orange cables. One day I want to a talk by the actually quite good Cambridge Computer folks where the speaker, Jacob, said something like “SANs are just disks talking over the network.” This was water in the desert and helped me sort my confusion into bugs, immature tech, and things-to-learn.
    2. Similarly, this talk by Corey Quinn, “Docker Must Die: Heresy in the Church of Docker” puts operating system containers in historical context, starting at about 5:52 in the video.
  6. Share novel learning methods.
    1. Sometimes I think of tools I’m using in spatial terms, even tactile. Sometimes I envision clusters of products and buzzwords in a family tree. I’ve often assumed that my way of thinking about these things was weird, but then been surprised when my explanation made total sense to someone else and helped them out of a tough spot. I’ve also been incredibly grateful when others shared their interesting ways of understanding a topic. So I will trust that someone else might benefit from my weirdness.

If I missed something, leave it in the comments and we’ll make a great pledge together!

Leave a Reply

Your email address will not be published. Required fields are marked *