Made by 
Made by
July 8, 2019
Client Relations Exec at Hoopy, the developer relations consultancy.
Learning developer tools can mean taking on some pretty tricky concepts. Providing the right context helps people to get over learning hurdles.
Here, in her talk from DevRelCon San Francisco 2019, Judith Malnick shares her advice for meeting learners where they are.
I think that this talk is going to tie really nicely into the last talk. I’m here to talk to you about how providing context can help developers learn faster. So why am I talking to you?
My name is Judith Malnick. I am currently an Education Engineer at Hashicorp. But this isn’t a Hashicorp talk. This is, basically, a talk that I thought of when I was first getting into tech because I don’t have a tech background. I come from academia. So, I have a lot of teaching experience with college students and volunteers, and elementary school kids, and high school kids for volunteering opportunities.
But I’ve only been in tech for about five years. And so, that experience of, like, what the heck is going on here is still pretty fresh. So, we’re going to talk about why you should give new developers context, how you add that context, and how you avoid bogging users down with the context you’re going to give them. So, part one, why give context?
So, the first reason to give context is that students who recognize patterns learn faster. So, when I was first getting into tech, I came from biology, and I was struggling to learn Git. I was like, “What are we doing? Like, why are there all these branches? This is so horrible.”
But eventually, I learned it. And I started writing blogs about it. And my partner who also is not from a technical education background was like, “How did you learn Git so fast?” It took me years. I still don’t understand it. What the heck is going on?”And the reason is that I was already used to thinking about really messy branching patterns. The first thing you see up here is a tree of horizontal gene transfer in, like, early bacterial and single cellular organisms.
And the second thing you’ll see is the, like, Git tree for console. So, they look kind of similar. I had somewhere to place this knowledge. And so I was like, “Oh, I’ll slot that into my complicated branching structure part of my brain.” So, context can really help people catch on faster if they’ve seen something like that before.
The second thing is that learners are busy. So, explaining why they need to do something can really help reduce the frustration that comes from trying to learn something really new and foreign. So, when I was first learning Git, I was like, “I don’t understand why we need to do these things. Why should I make a branch locally if I’m already forked it remotely, right?” And the reason is because you need to test it locally, and you don’t want to commit things and blah, blah, blah.
But I didn’t know that and so I was mad. So, we can help people be less bad, and that’s helpful. So, what’s changed now? Why is it important now? According to Stack Overflow’s 2019 developers survey, only 49% of developers have any bachelor’s degree and only 31 in computer science. The reason I think this is important is because when you’re learning something in, like, a higher education program, they take a lot of time to give you this conceptual framework, and you’re kind of a captive audience, honestly.
Like, you know, you’re in your 101 class, and they’re like, “High-level things, concepts.” And you’re, like, not in so much of a hurry to, like, go get a job. So, I think that as new developers are coming in from code camps in other, like, different backgrounds. They’re hitting the ground running, but they might not have the same, like, conceptual knowledge that you would expect from developers in previous generations.
So, what happens when you’re learning this way? Well, you take the thing you learned, and you stack it on top of the last thing you learned, and then you take the next thing you learned, and you stuck it on top of the last thing you learned. And you’re in this, like, where do I put this? Where do I put that? Just make a big pile mode. And this can cause some problems for people. So, sometimes they’ll miss the point or value of a technology like I did with Git.
They might take longer to learn. They might have difficulty communicating with their colleagues because they don’t have the same baseline knowledge. You could construct a bad information architecture if you’re left to your own devices. You can be more frustrated, have trouble extrapolating the behavior of a system in a new context.
Or worst case, if you’re, like, in production already, there could be downtime or giving up. But it’s not all bad, right? There are some serious advantages to learning this way. You know, the problem is that people will make their own context. And also, the strength is that people will make their own context. So, they’ll come in with a beginner’s mind.
They’ll find creative use cases and implementations for things. They can bring in stronger connections with other fields. So, like, I tie in biology concepts to my work all the time now, which I wouldn’t be able to do. They may end up with a deeper ultimate understanding because they do have to do all of that work to build that model and nobody hands it to them, so that’s really important.
People have unique points of view that they can bring into tech. And the practice itself of building a conceptual model can help you as a software architect later on in your career. So, when you’re saying, “I’m going to put all these ideas together into this coherent point of view,” that’s something that you’re going to need later on. And having had to practice it is really, really helpful.
So, what we want to do is basically help these developers to come in and get the knowledge that they need to be less frustrated and be more successful, and recognize that they have a lot to offer us in return if we do that successfully. And so, part two. How do you add context? So, I’m going to talk about three different ways to do this.
And the first one I like to call “eat your vegetables.: And it’s basically, like, if you’ve ever seen the architecture section of documentation, right? It’s like, internals, architecture, and you go there, and they’re like, “What is the architecture of this thing? How is it put together? What consensus algorithm does it rely on?” That’s the first part.
This is my favorite way to consume concepts, but my favorite food is salad. So, I’m, like, pretty much alone in that. But it’s great. It’s easy to find. It gives people the big picture right away. The disadvantage is that it’s opt-in. So, if your favorite food isn’t salad, you might not find this and you could still be missing the context that you need.
The second strategy I like to call “listen to your inner kid.” Anytime you’re writing documentation, and you’re like, “Do this, do that, do the other thing,” and, you know, your inner kid’s like, “Why should I do that?” And you’re like, “Because I said so.” Don’t do that to people. It’s mean. So, whenever you want to ask yourself, like, “Why are we doing this? What is it connected to? Like, why is this happening? Why is the sky blue?”
Like, you can say that to people and just call it out. It’s helpful and it motivates learning, but it does have some dangers. It runs the risk of bloating your docs and it can feel really basic for experienced users. So, you want to be kind of judicious about how this is going to happen. And I’ll talk a little bit about that in the third section of, like, avoid bogging people down.
Yeah. So, here, we’re going to register our health check as critical because your service is still coming up. And once it’s up, then it will change the health checks. The last one is called just in time. This is basically, you want to call something big out to users when they’re about to shoot themselves in the foot. And as we support communities, we have, like, the advantage of being able to hear from people when they’re shooting themselves in the foot.
And we can add that to our documentation and be like, “Everyone trips up here.” So, you can see this big yellow box in our documentation that’s like, “This a common mistake. Don’t do it.” The advantages are that it gives people context and everyone’s really motivated to read it because it’s, like, danger. But the disadvantages are that it doesn’t really give people the full picture of the context that you’re trying to get to.
It’s just, like, a little snippet of like, “Don’t do this.” So, how do we avoid bogging our users down? The first thing I would say is to separate your concerns.
So, there are kind of two types of documentation in my mind. There is learning documentation, where you’re explaining things step by step, and you want it to be a springboard where people can go.
And if they want to learn something new about, like, this other thing that they read about, they can go do that. And they’re kind of just mucking about and trying to get things spun up. But there’s a second type, like, reference docs, which is like, “What is this command? I forgot it. Or how do I hit this API?” So, this lady here, she is our expert user, and she’s, like, slogging through mixed type docs, being like, “I just need this command. Why am I reading about all this conceptual stuff that I already know?”
So, separating that out and labelling it can be really helpful for both your beginner users and your advanced users. The next thing is to be strategic about linking out. I did a brief, brief stint in marketing. And the one thing that I learned is that it is really hard to get people to click links unless you don’t want them to click them.
And in that case, they’re just going to click away from the page they’re on immediately. So, you want to be strategic about when you’re linking out. You should probably include the text if somebody needs that text in order to complete their tasks. So, if they’re not going to be successful, unless they know something, don’t count on them to, like, click a link to get there. If they will break something without knowing this, you should tell them right away.
And if the explanation is really short, then you should definitely include it because nobody wants to do all the work of, like, clicking out and reading through, and then it’s just a tiny sentence. So, you’re like, “Why didn’t you say it?” You should link out if the explanation is optional or really long, or your docs are learning docs, and you’re trying to provide that springboard for people to kind of explore and go out into the world.
My third tip here and there, four of them. The third tip is to write really clearly. So, we’re all explaining really complicated concepts anyway. And what we want is to make those concepts as easy as possible to understand and writing clearly can really help users with that.
So, right in plain language, use the active voice, right in chronological order. So, don’t, like, say the result and then say, step two of what you have to do to get there and then say step one because that’s horrible. And find an editor because even the best writers are not going to have the fresh perspective that they need in order to empathise entirely with their audience.
So, even if you’re an expert, maybe even especially if you’re an expert writer, find some human who is not you to read your docs and tell you if you’re making sense because it’s really, really hard to do this for yourself. I just want to plug a great Coursera course called “Writing in the sciences” that I took when I was in grad school, and it changed my life.
Like, I wouldn’t be here today. It’s awesome. So, go look at that. There’ll be a link in the slides. And the last tip I want to give you is, remember WAIST. WAIST stands for “Why Am I Still Talking?” It’s basically the idea that if you are not telling somebody something to help them or to help them succeed, then probably you shouldn’t be talking to them at all.
So, you know what? That’s great. Thank you.
Oh, does anybody have any questions?
Audience member: I don’t know if this is a basic question. Hey, great talk, Judith.
Judith: Thank you.
Audience member: So, you mentioned breaking out, like, learning docs and references. Like, how do you keep everything up to date and in sync? Or is that a basic question? I don’t know.
Judith: Oh, no. That’s not a basic question at all. So, this is actually one of the things that we’ve been thinking about a lot. And I think one great way to do this is to keep everything in the same repository. You keep your code, your docs, you’re learning docs, all in the same repository. And that means that when you update a setting or when you update how something works, you can grep through that code base really easily to say, like, “Where are all the places that we’ve mentioned this before?”
And update them all at once. And so, that means that you don’t have these, like, straggling. Like, did you check here? Did you check there? Yeah. So, I think that can be really helpful. And if anybody else’s ideas about how to do this, I’d love to hear them also.