Making the implicit explicit

So I'm gonna be talking about making implicit things explicit, how you can model developer norms and tools. And obviously, you're now about to become very good at everything, but this is not true. I just find that people really enjoy seeing this slide before a talk because it makes them feel like they made the right decision being here. So, yes, hi, I'm Erin McKean and I am a developer advocate at IBM, on the San Francisco City Team. And yes, I am jet-lagged, thank you for asking.

And I also run wordnik.com, which as Matt said, is the biggest online dictionary by number of words, not by number of visitors. And it has an open API. And in the last couple of years, I've gone from being a full-time lexicographer who does DevRel for the Wordnik KPI on the side, to being a full-time developer advocate who does lexicography on the side. And, one thing I learned by making that transition is that actually developer advocates and lexicographers are both concerned with the same thing, and that is, "What do people know?"

Getting in the know...

So, basically, when you're creating instructional material, whether that's a dictionary definition or a tutorial, you're thinking, "What does my audience know, and what do they need to know? And essentially, how is knowledge acquired?" Which is epistemology. And so, you're not really supposed to use a word like epistemology either this early in a talk or this early in the morning, so, I'm sorry about that. Bear with me. But epistemology is, of course, the branch of philosophy that deals with the study of knowledge. Like asking questions like, what is knowledge? And how is knowledge acquired? And how do we know what we know? Like, this is kind of deep and heavy stuff. And when you're thinking about this, you also think, "Okay, well the..." You might think, "Well, I don't really do epistemology, I write demos." But when you're writing demos or tutorials, your audience has epistemic goals. Basically, they want to know stuff.

And we tend to actually, you know... This slide is supposed to be a joke, but it's actually one of those "It's funny because it's true" jokes. Because sometimes people in our audience have possibly unreasonable epistemic goals, right? They want to be very good at everything. And our response as developer advocates is often, "Look, I can teach you how to do it." I've been trying to figure out, like, how I could represent, like, orally, this particular kerning. I haven't got it right yet, like, "I can teach you how to do it." But there are a few problems with this. Like, we think, "Oh, yeah, I can teach you how to do that." But, who is the you, and what do we mean by how, and what is it? And answering these questions correctly helps us make sure that we are setting and achieving the right epistemic goals for our audience.

And also, this means that if you get tired of calling yourself, like, DevRel or a developer advocate, you can now call yourself an applied epistemologist, which I highly recommend. And so, when we're thinking about the who of the "I can teach you how to do it," we often think of developers only in like three channels. Like, school, right? Or work, or people who are self-taught. And we say self-taught but that, in my opinion...I really like to say community-taught instead. Because people who are learning, like, web development, for example, are not, like, sitting down and intuiting how to build a web page from first principles, right? Like, they are learning from demos and tutorials and conference talks.

And of course, there is a lot of overlap in these channels, right? Nobody learns just at school and nobody learns just at work and nobody learns just, you know, by tutorials. And, thinking about these channels can be helpful when we're thinking about the who, but I think it's important not to use them as an excuse or a way to, like, shift responsibility. Like, you shouldn't be thinking, "Oh, well, you should have learned that in a formal CS program," or, "You don't need to worry about that until you're on a team that's doing production deployments," or, you know "Oh, there's tons of tutorials on this particular topic, you can go look at one of those." Right? When you're thinking about the you, you wanna really think about, like, what can you bring to them and not what they should have learned somewhere else. Because should is meaningless. You can't say should to someone.

...and finding the know how

So, if those are the possible you's, what's the it? I'm just gonna assume that whatever your it is, it's a good idea and that it's something that people want to learn. So, I'm gonna leave aside it for the moment and think about the how. And when you're thinking about fulfilling people's epistemic goals, that's where you get sneaky. Your user really has two goals. The first is that they want to learn whatever X it is, whatever it is that you're running a demo for, showing a tutorial of or talking about. How do you use Loopback, for example, or Docker, or your API, or what a monad is, or anything that you're trying to teach people.

And the second thing that they wanna learn, the second goal that they have is they want to learn how to be good developers. And, if you just show them whatever technology it is in a vacuum, you may fulfill that first goal. You know, they may walk away learning what a monad is, although, frankly, I never have, no matter how many times someone has tried to explain it to me. But you might not get them any further towards their second goal of being a good developer because they're just learning one tiny, little thing. So, how do you help your audience make progress towards their second goal?

Salience: not a mug’s game

There are a couple of things that you can check for in your examples, and I'm going to talk about three of them today: salience, prototypicality, and mapping. So, salience, a salient feature is something that's noticeable or important even though it might not be essential to something's functionality. So, you can drink your coffee or tea out of a blank mug and it will taste just the same. But a salient feature of mugs in western office culture, is that they have funny sayings on them or brand identifications because you want the user to be able to display some facet of his or her personality.

So, you might think that leaving out a salient feature in your example makes things easier but it's the equivalent of sending your developer into a new office with a blank mug. A big example of this and one that I'm personally guilty of, is showing demos that build APIs or sites with user information, but leaving out the authentication step, right? Of course, your thing works, but authentication is a salient feature of APIs. And so, a hint that you've left out something salient is if you say, "Don't do this in production" in your example, you're probably missing a salient feature. And, the problem with that is that no matter how many warnings you give to people, and no matter how wrong you think something is, and no matter how many times you warn them not to do it, they will do it anyway and they will get mad at you.

And honestly, it is kind of your fault because you said, you know, "Don't do this," knowing that human nature is that they're gonna do it. And often, if they don't know enough to know not to do the thing, they will ignore your warnings because they don't know what the consequences are. So if you leave out salient features, that can be a problem.

Prototypicality: look for the common bird

So, prototypicality is kind of related to salience. So if I ask you all to think of a bird, very few of you will think of an ostrich, because an ostrich is not a prototypical bird. Usually, when people are asked to think of a bird, they think of robins or sparrows, depending on where they live. And an example of demos and tutorials that are not prototypical is writing demonstration functions that do simple mathematical operations. That is not really a prototypical use of functions outside of textbooks. How many people write a function when they wanna do simple math? Nobody. I never write a function to do simple math. I use Apple Spotlight to do simple math, like Steve Jobs intended. So, when you're trying to show a technology, you think, "What are most people, what are normal people...what do people in the real world use this for?" That's usually your prototypical example.

Mapping: always take the bus

And then the last thing I wanna talk about in terms of examples, is mapping. Mapping is just making sure that you help your audience understand where a particular technology fits in their mental map of how things work. When I have time in London...the best way to learn London is obviously to walk it. But when I have time in London, I like to take the bus instead of taking the tube. Because when I take the tube, I actually don't have any idea how the place where I start my journey and the place where I end my journey are connected. Like the tube map is a very abstract map. And so I'm like, "Oh, I got from A to B, but I have no idea, like, what kind of tesseract folding had to happen in the universe to make this, you know, journey happen." And a bus ride lets me stitch the neighbourhoods together because I'm over land, I can say, "Oh, this is where this neighbourhood turns into that neighbourhood."

I think it's easier to do this in our examples than we think. We don't have to show something isolated, we can talk a little bit about how this fits into the universe of things. For example, I saw a really good demo, a lunch and learn actually sponsored by the San Francisco team about Kubernetes a couple weeks ago, where the presenter spent a lot of time comparing and contrasting virtual machines and containers and clusters so the audience had a better idea of the relationships and the trade-offs involved. So, salience and prototypicality and mapping are all kind of implicit information about the universe of code that you probably know but that you can make explicit when you're building demos and tutorials.

What are the needs?

So, really, these things help you think about, like, what does the developer, what does the audience that you're talking to need? And they need examples that include these things. And also, I believe that it's the law if you say the word "Need" in a presentation, you have to then show Maslow's hierarchy of needs, from his 1943 "A Theory of Human Motivation." And everybody has seen this pyramid before, right? Like, this pyramid is like a very pervasive and contagious meme, because once you have this pyramid, you just want to expand it to every single domain. So you might wanna build one for coders that looks like this, right? Probably it looks more like this. But this layout is kind of deceptive. Like, this pyramid is deceptive because it makes you think that you can just climb the ziggurat of developer knowledge one step at a time and it's okay to stay stuck at a particular level, like, "I'm just gonna talk about...I'm just going to give you the WiFi password. Then we're done," or like, "I'm just gonna talk about code," or, "I'm gonna spend a whole bunch of time talking about tools," and treating them as different levels.

And there's a lot of content that reinforces this idea. Obviously, epistemic proof through Google is not really that valid. But, come on, like, there is a lot of this and it can be really boring to learn things this way. Because it's harder to memorise a list of random numbers than it is to learn an equally long story. And I think it's often really hard to go from those lists to real knowledge because you lack context. And this is the most context-free image I could find on Flickr. What is going on here? I do not know. There is no knowledge around this photo. I have no idea what's going on here. And sometimes, this list makes you feel the same way. Like, what? So, maybe instead of a stepped pyramid, we want something like this. So, think about, like, when you're running a demo or a tutorial, you're not stepping up. You're, like, taking a core sample, you're gonna drill through all these layers, and your tutorial is gonna have a slice of each of these layers. And some slices may be thicker than others, but all of them should be included.

And of course, so maybe right now you're saying, like, okay, nobody says, "I'm gonna teach you how to make a sandwich, but we're gonna start by just eating a slice of turkey to keep things manageable." That's not how sandwich-making works, right? And nobody says, "Okay, well, we're just gonna focus on the theory of sandwiches." I'm not gonna mention hot dogs here. I'm not gonna mention hot dogs here. But, okay, I'm gonna briefly mention hot dogs and sandwiches. So, my proof for sandwichness is if someone says, "Hey, can you pick me up a sandwich?" And if you bring them back something else and they don't punch you, then what you've given them is a sandwich. Like, that makes sense, right? Okay. But anyway, the temptation could be to focus very low level, like of that pyramid on the code, or very high level on the theory.

Theory and practice

This is one of my favorite T-shirts of all time because I'm an alumna of the University of Chicago, so, basically, like, well, that works in practice, but how does it work in theory? And the thing is, is that if you focus too much on theory and ignore the practice, that's equally bad. Because it is entirely possible, as Michael Polanyi said, "To understand the physics involved in maintaining a state of balance but still being unable to ride a bicycle." And that is the downside of focusing mostly on theory. But you may be saying now, "Erin, I cannot possibly include all this in every tutorial and demo," and that is true. You have to pick and choose. You have to decide which of these layers in your core sample is gonna be the thickest. And, that's because, as George Box, the British statistician, said, "All models are wrong, but some are useful." And he also said that, "The ability to devise simple but evocative models is the signature of the great scientist." So, perhaps all tutorials are incomplete but some are useful, and the ability to devise evocative tutorials is the sign of the great developer relations person.

But, how do you decide whether a tutorial is, like, usefully incomplete? Did anybody have this toy as a kid? I'm really old, so probably you don't remember this. This was called Dapper Dan, and it was not like a super fun toy. They don't make it anymore because there is no way that this competes with like YouTube on an iPad. But it's basically a getting dressed tutorial for toddlers. It had buttons and zippers and shoelaces to tie, and everything was functional and salient and prototypical and the right relationship to one another. It was well matched. You couldn't zip the pants after you've buttoned the vest. Like trousers, you couldn't zip the trousers. And, anyway, this obviously, this is an incomplete tutorial, as anyone who's ever tried to teach a toddler to put on his or her own socks knows. But, it was very useful. And so, thinking about, like, how to make a useful tutorial, I think of this model like, "Does it have everything that you need to know? Is everything in the right place and in the right relationship to each other, even though this is not complete, right? There is no hats. You know, there are no socks.

Teachable moments

But the last one I wanna talk about how to satisfy your audience's epistemic goals is by being a role model. Basically, every time you give a demo or a tutorial, you have opportunities for teachable moments. Teachable moments is actually the term of art. That's really what's they're called. I once worked on a reading textbook and I had to write a bunch of teachable moments, and I can tell you from experience, it is a lot more interesting to think about teachable moments for software developers than it is to think about teachable moments for second graders. As much as I love long vowel sounds, teachable moments for software developers is way more fun.

And there is a lot of pedagogical research that shows that if you teach skills in context, and this is a slide I totally yoinked from Flickr because lots of teachers talk about this and they share their slides. The things that every developer should know are often disconnected from tutorials. But to be really effective, you should teach these skills during your demos. And so, there a couple of different ways that you can do that. One of the things that I love to do, is I love to show keyboard commands for editing the command line, because life is too short for backspace.

So, like, you know, by going Opt-left, you can delete a word to the left, Ctrl-E will take you to the end of the line, Ctrl-U will kill the whole line. And this is something that you can do very easily when you're in live coding, and it's a way to implicitly show how things work. This is actually a twofer because at the same time, you can talk about how to modify your shell prompt, I used ZSH, or OMIZSH and also using something like NVMRC. So every time I switch into a new directory, I have MVMRC file that tells me which version of node I should be using for a particular project and it switches it automatically, which I think is pretty awesome. Because the fewer things I have to remember at my advanced stage, the better.

Don’t over-estimate the knowledge

So, another thing that I love to model is using little tools like clipboard managers. How many people here use a clipboard manager? Yay. I'm often surprised by how many people don't use the clipboard manager. I think they're super useful. If you don't use one, try it. You'll like it. Basically, it lets you save your copy and paste history for, like, ages, and bookmarks certain copy and paste fragments. Like, you might use a macro expander, like TextExpander to do the same thing. I use something called copy and paste. You might think that everyone knows all this stuff already. No, they do not. And in fact, the idea that most people don't know what most other people know is one that has a long history. Like, Piaget was talking about this, like, decades ago. He says, "Every time somebody begins to teach something," he finds out that, "Oh, my goodness, nobody in the audience understood me because I didn't know what they didn't know."

And there is a lot of epistemological research that shows that you are very likely to overestimate the extent to which a random other person's knowledge mirrors your own. So, you tend to think that other people know exactly what you know, and they do not. In fact, this happened just the other day on Twitter, right? I actually have a UNIX sysadmin certificate. I have a piece of paper and everything. I, like, sat through an entire course on UNIX commands. I didn't know this command. People overestimate what other people know. So, don't hesitate to show off things that you think are useful that make your life better, that you think help make people good developers.

Making mistakes: learning and perception

So, one of the other things I wanna talk about is one of...a good way to model expected behaviour to developers is to show what you do when you make a mistake. Now, obviously, when you're live coding and the demo gods frown on you, all you wanna is, like, recover from your mistake, get back on the happy path. But showing how to troubleshoot and how to debug when things go wrong unexpectedly, is hugely valuable. And it's something that a lot of developers, like, take a long time to learn. So, when you make a mistake, like, you know, go deep, like, just show what you did wrong, show why it's wrong, show how you figured out that it was wrong. Like, one of the things I do over and over again, is I will have too many node processes running at the same time and then I get an error "No ent" . I was like, "Oh, yeah, I can't run another version of Loopback because I already have a version running on the same port, and it doesn't like that."

So, explaining that kind of thing to developers really helps them. I do want to point out that this can be problematic, especially if you're an under-represented person in tech, because if you screw up, even if you screw up on purpose to show how to fix things, there is a chance that other people will use it to reinforce their stereotypes about who is a good developer and who is not, and that sucks. So, just be aware that you might think, "Oh, I made a mistake, and now I'm gonna show people how to recover," that there might be people who think, "Oh, she made a mistake. She's terrible."

Please don’t tool shame

So, another thing that sucks is tool shaming. Everyone has preferences around tools, and it can be hard to give a demo without standing for a tool that you really love. But it's better to say, "I find this tool helpful and it helps me do X, Y and Z," and not, "All good developers use this tool," right? So don't shame people for the tools they use, just show the tools that you like. And if your tool is really great, by example, you will show that it is better. It's hard to make demos. Tutorials are time-consuming to put together, but you can get more bang for your buck or heft for your brick and achieve more of the epistemic goals for you and for your audience if you incorporate teachable moments, if you give full context, if you think about salience and prototypicality and mapping in your examples and your demos.

So, one of the other things I learned while working on elementary school reading programs, is that if you sit through an entire...if you sit quietly while the teacher is speaking, you get a sticker. So, if you wanna come up to me afterwards and get your Semicolon Appreciation sticker, I will give you a sticker. I have lots of these to give away if you want one. If listening to me talk has made you think that, "I don't want a sticker but I do want a new free IBM Cloud Lite account, with no expiration date," you can sign up one here free with this link. You can have both an IBM Cloud Lite account and a sticker. But I hope that your epistemic goals have been satisfied by this talk. Thank you so much for your kind attention. And, you can reach me on Twitter. I also would like to thank the fine people of Flickr, fewer and fewer of them every day now, who openly license their images. This whole presentation is CC by NCSA. If you would like this set of slides to give a completely different talk using these same images in this same order, I'm happy to share them with you. So, thank you so much.