One size doesn’t fit all


Amara Graham speaking at DevRelCon San Francisco 2019

Amara Graham

Amara Graham transitioned from enterprise developer to developer advocate, with a history of helping developers implement proprietary and open source solutions. In this talk from DevRelCon San Francisco 2019, Amara explores how to make sure your content is enabling your community.


Again, my name is Amara Graham. I’m a developer advocate with IBM and I want to take you on this journey. It was about, I guess, a year and a half-ish, maybe two years now, through this kind of side project turned not so side project. So what I mean by that is… this is me at Unite L.A. Shout out to the Unity folks that are here, the one. So I am, I guess, an enterprise developer in training or, I guess in my schooling, if you will.

I’m not a game developer and I’m very, very clear about that when I talk to actual game developers because I don’t want them to be like, “What is she doing talking about game development if she’s not a game developer?” Very clear about that, very upfront with that.

But what I am is an IBM developer advocate. So if I can tie IBM stuff to, basically anything, I get to talk about that, I get to talk to developers, I get to help them.

And one of the things I realized that I was really good at was helping developers on their AI journey. So AI, artificial intelligence, and what I mean by that is the beginners, the people who are like, “Hey, my boss woke up this morning, listened to NPR, and now wants something in machine learning.” Doesn’t know what that is, they just want it. But that’s also the developer that’s like, “Hey, it’d be really great if we had speech to text and text to speech and I don’t want to build that model.” Awesome. I can talk to you about that too.

So, this is me in front of some Unity developers talking to them about how to work with IBM’s Watson APIs, so that they can build AI into their games without having to build machine learning and deep learning models themselves. It’s a really cool audience to talk to. If you don’t currently interact with game developers, I highly recommend it. They’re like the scrappiest, coolest people on earth because you give them something and they’re going to hack it to pieces to get it to work because that’s what they do. And they’re fun.

But, if you know anything about IBM, other than the fact that it’s huge, we have a massive portfolio and massive is probably the worst word to describe it because it’s bigger than massive. So this is our advocacy homepage, if you will. It’s IBM Developer. It’s the program that you’ve heard us speak about if you’ve ever heard any of our advocates talk. And it houses literally everything content-wise from advocacy. And this is just a very small screenshot.

So this is not all encompassing of everything that we do and talk about. And my little piece over there in AI land is that’s actually really deceiving, because it explodes out into thousands of different things. So, okay, we’ve got this nice place, you can go and you can search, you can find the different things that you’re working on. Well, I kind of mentioned these game developers and now I’m saying like, “Look at this website of stuff that we have. It’s huge.”

I’m going to make you do a quick thought exercise after lunch, which I know is super exciting. You can participate, you don’t have to, it’s fine. We can make this up as we go along. But, what I want to do is kind of run you through some of the things that I was thinking about when I first started this journey of interacting with game developers, helping them with AI.

So, I’ll start with one of the things that I have asked myself and I’ve heard other people ask me.

What is an enterprise developer?

What is an enterprise developer? So when I say enterprise developer, what are some of the things that come to your mind? And we can make sweeping generalizations so long as we’re not mean. But I was an enterprise developer at one point, so you’ll see my bulleted list is very much about my experience and what I did, and I can kind of be mean to myself.

So, does anybody have any ideas? Enterprise developer, just shout out what it makes you think.

Audience member: Java.

Amara: Java.

Audience member: Legacy.

Amara: Legacy. Nice. Okay. Oh, yes. Oh, this is great. It’s like I’m paying people at this point. All right. So, here’s my list and my brain thinks in lists and buckets. So you’ll see that throughout my presentation. You don’t have to read the whole thing.

But, for an enterprise developer, we’re thinking mid to large company, they’re going to sit in IT or some sort of software services group. I heard somebody say… I heard somebody say, “Waterfall.” They’re working in agile, sometimes it’s wagile, sometimes it’s something that’s not even waterfall or agile.

Comfortable with acronyms. I love that one. Integration with Salesforce and SAP. Of course, because how can you run a large company without them?

Doing something in open source. We’re not always sure what, but they’re doing something there. Access to training and a budget that’s greater than $0 even though I have previous managers who would argue that yes, the budget was $0, it wasn’t.

This is their day job

Cool. So, all of that and we can probably all agree with this last bullet. This is definitely their day job. No one goes home from their day job to be an enterprise developer. And if you are, that’s really strange to me.

So, these people get paid to do this. This is their day job. They come home, they might do other things but they’re an enterprise developer 9 to 5-ish, right?

What is a game developer?

So, if you can kind of see where this is going, this is a conversation that I had to have with my management.

What is a game developer? And again, don’t be mean. But what are some of the things that you think about when you think about a game developer?

Audience member: Hardcore.

Amara: Did somebody just say hardcore? Yes. I like that. Anything else?

Audience member: Physics.

Amara: Genius. Physics engine. Okay, yeah. Oh, I like this. And it’s just funny because I did this talk before and I got totally different answers. So, I feel like I just need to keep doing this with different crowds and see what I get. All right.

So again, here’s my big jumbo list and you’ll notice, it’s a little bit more verbose than the last one because this community is not quite so cookie cutter.

Fluid definition

And again, sweeping generalizations here, but we have a fluid definition.

So you can be a game developer at an indie studio and your indie studio might have two, three people, but you could also have a triple-A studio. And if you’re not familiar with that terminology, triple-A is going to be the people who are, like, making the huge titles, like the things that you see, the giant billboards of your Call of Duty, Assassin’s Creed type games. And then, of course, everything in between. So, you might have a one-person game development team to, I don’t know, a couple hundred.

The second bullet’s kind of interesting. Designers and artists will come up to me at workshops or at conferences, come up to the booth, and they’ll tell me that they’re not technical. I’m like, “You just showed me the app that you pushed to the App Store. How did you do that and you don’t consider yourself technical?” I’m not talking about writing code. They just said that they’re not technical. Like you built this incredible game, you’re technical. Give yourself some credit.

Varying skills at varying levels, again, I mentioned that this group is really scrappy. That comes out in those skill levels. And like I said, if you give them something and they want to make it work, they’re going to make it work, but you’re going to be like, “Wow, it’s a really roundabout way to go about doing that, but you did it, so that’s cool.”

Varying levels of time commitment. They may see teammates that are at game jams or online only. They may never be really face to face with those teammates that they have, the folks that are writing the games with them.

I always like to put in, “They read all the Ts and Cs for each game engine before picking which one would take the least of their money,” which is also really important because they do tend to read Ts and Cs for other things. Ts and Cs is terms and conditions. They seem to be the only group of developers that does that. I think everybody else is like, “Yeah, click, click, click, click. Done. Download.”

Team structure could be one, could be many, like I was mentioning. And then I’ll jump down to the bottom one, a very questionable budget because sometimes, it could be free, sometimes it could be, you know, “Yeah, we do have some budget to spend a little bit more on something here.”

This may not be their day job

And you probably kind of have an idea where I’m going with this at this point. But this may be their day job, second job, hobby, passion project, somewhere in between. So, very much unlike our enterprise developer folks who are not going to be doing this in their evenings, their nights and weekends, casually haphazardly throughout the year, this is definitely potentially a side project for folks.

So, another shout-out to my friends at Unity. When I said, you know, “Hey, I’m really interested in figuring out how I can work with game developers and how I can help them with AI,” Unity was really great about talking to me about their community. And I love saying Unity community. If I can say that, like, all the time, it, like, just makes me happy.

Nights and weekend developers

So they’re really good about talking about their community and saying, “Hey, we have a lot of folks who we consider nights and weekend developers.” And I was like, “Okay, that makes sense.” So it’s the folks that have the day job, maybe they have kids, they have a family, they have other hobbies, and they’re trying to build a game or they’re trying to up their skills in some way, shape, or form.

But again, going back to that enterprise developer doesn’t come home to be an enterprise developer, you have someone who’s potentially, I don’t know, a CPA during the day and trying to build a game at night.

So, immediately, this kind of started shaping some of the things that I was thinking about. How do I enable these folks? So, how do I go out and do advocacy to folks that maybe are already spending a very, very small amount of their day working on their side project? How do we make sure that they feel enabled and welcomed to use things like our APIs, work through our documentation, things like that?

Game dev considerations

So again, you don’t have to read this whole thing. To Kelsey’s point, I think about slides, I almost just want to shut the computer and just be like, “Yeah, listen to me talk.” But I know you have to look at something so you can look at this.

So, some considerations that I started going through, and I know immediately, someone is going to ask me about the asterisks. The asterisks are things that I want to get better at myself, things that I know I’m not doing a great job of right now. But these are some of the things that I was thinking about very particular to what I’m working on within IBM. How could we take our existing content and make sure that it was applicable to this group of developers?

Yes, we say we’re targeting enterprise developers, but we also kind of casually throw around the fact that we’re open and welcoming to all developers. But can we really do that when we have a lot of considerations to keep in mind for our game developer audience?

Right length and skill

So, I kind of started walking through, and again, I love lists. I make lists about lists. So, this is pretty much exactly how my brain started going. How do I get to the point where I can make sure that my content has the right level of both length and skill, that I can capture someone’s attention but not hold it long enough that it’s going to be problematic?

Like, if someone sits down and they said, “I have an hour to work on my game.” They’re so excited to do that.” How can I make sure that my content is bucketed or bundled in such a way that in that hour that they spend with our technology, they get the most out of that?

So, keeping into consideration the attention span and the quality of attention. And I’m sure you’ve done the same thing when you’re learning something different. Sometimes you can devote a huge chunk of time, sometimes you’re constantly context switching and you’re trying to figure out, you know, what can I absorb in the 20 minutes that I have between meetings? Or maybe while you’re not on the plane and you have internet connection, things like that.

So how can I chunk up things like how-tos? Could they be a series? Could I have something where I’m going to build a little something, build another little something, build another little something, and at the end of that, you have a full complete solution or a more complete solution?

Time estimates

Things like time estimates, if you don’t have those on your how-tos and tutorials now, I highly, highly recommend them because there’s nothing more infuriating to me as a developer to sit down and say, “Oh, I think I can do this in about three hours.” Get 10 sentences in and go, “Oh, dang, this is going to take two weeks.” Like, that’s not fun.

And I totally get that it’s an estimate and I think everybody understands that it’s an estimate. We understand that you can come in with different perspectives, different paradigms, maybe you have a workspace that’s already set up and running, but just some idea of how long this maybe should take me is much better than just a whole bunch of text on down.

Level indicators

A level indicator is also really good. Folks do ask, like, how do you determine the difference between beginner, intermediate, and advanced? It’s going to depend on your product. It’s going to also depend on your developer community.

But what I always say is if there’s any sort of prerequisite, it immediately bumps you from beginner into intermediate, in my mind. If you have something that should already be set up, go ahead and push that into intermediate or advanced level because you never know.

Sometimes people have Python 2.x installed instead of 3.x, and it’s a world of hurt to move from one to the other if you have a bunch of dependencies, things like that.

Content types for your community

Video versus written could probably be a whole different talk because depending on how your developer community consumes content depends on whether you’re going to have that as a video format or whether you can have that just like a full, written-out tutorial or maybe you have both. Who knows?

And then auditing existing material, which we’re going to talk about on the next slide here. So, originally, when I pitched this, kind of, idea, wow, I thought this was going to be the ugliest-looking slide, but we’re looking pretty good. So, what I originally pitched to my management was “Hey, I want to go after these game developers. I really think that they would be interested in AI, and I think we can do it in such a way that I can bundle existing content and just kind of remarket it,” which is kind of a weird thing for me to say as a developer.

I’m like, now, I’m talking about marketing to developers or changing the lingo that’s on the page, changing it a little bit. That’s odd. But I said, “Hey, I think this is a low-hanging fruit exercise. I think this will be the easiest way to go about it.”

So again, buckets and lists, I’m all about it. I said, “Okay, enterprise developers, that’s the folks that we’re targeting today. And then I have kind of these three other buckets of folks that are within the game developer community.” Saying buckets and not personas is because personas are going to be a lot more in depth than what I am offering here or the information that I’m showing, but these are the three folks that, if I were to sit down and truly detail out personas, these are where those personas are coming from.

Distinguishing criteria

So we need to have somebody who’s highly technical, someone who definitely considers themselves a developer. We have the artists and game designers, who are the folks that love to tell me that they’re not technical but they are. And then we have the folks who are hobbyists, who could theoretically also be in that artist and designer category, but I like to make a distinguishing set of criteria because I think the hobbyists are going to have that quality of attention spans, not issue, but the thing that will come up.

So, I was like, “Cool.” Manager. “If we have all of our existing content for enterprise developers, because that’s kind of our thing, how would that look across the rest of this?” So I’m like, “Okay, well, here’s some of the things, not only within AI, but here’s some rough ideas of content and where we’d kind of place that.”

Our highly technical folks, I’m assuming that they’re building game engine backends of some kind, so they’re going to be really excited when they see words like Kubernetes, maybe they’re going to be really excited when they see things like CoreML. I don’t know. But I think those are things that are going to speak to them.

So what about our artists and designer friends? They’re probably going to need some getting started with the Watson SDK for Unity, they’re probably going to need some sort of introduction to AI services in general.

Why would they want to use these? What problems might they want to solve? Really kind of spelling out some of those things that maybe our enterprise developer folks have heard about because that’s what’s being talked around the water cooler or things like that.

Same thing for our hobbyists. And which is why I said they kind of go together, but I like to separate them out.

Taking a step back

But what we actually needed, and here’s the kicker. I woke up one morning to an inbox full of people, different people, asking me how could they activate their API key with cURL. And I was like, “What?” So, we had a problem and it was not that game developers weren’t able to find our content, it’s once they got to our content, if you’ve ever been to one of our documentation pages, you’ll see that, particularly for like our Watson services, we have a number of different programming languages that we support. We have snippets for each of those, but the very first one for all of our documentation is cURL.

And those developers were getting to our documentation, they were looking at it, and they were going, “I don’t know what cURL is.” And I went, “Oh, no.” I can’t bundle up the content that we have and say, you know, “Here. Let me just say, like, oh, give me this little use case in game development land. Oh, that applies to this content. And, here, game developer, you’re off and running,” right?

No. We had to take it a step back and I had to write up things I never thought I would have to write up, like what is cURL and how does it relate to APIs? Because we could not get them to the point where they could get an API key and get up and running.

So, we really had to go back to the basics and figure out, okay, how do we really spell it out to these folks up to and including putting a API key that I did delete, don’t worry, before I published it. Putting it exactly in writing because they didn’t understand where to put the API key, that they need to remove things like quotes, or they need to remove things like brackets, things that are kind of considered standard for tech writers writing API docs.

So I generated a number of these pieces of content that I didn’t think I would have to do. Like I said, I was like, “Oh, we’re just going to bucket different things. We’re going to put up a game dev page for IBM Developer. We’re going to be good. And then we can figure out what content we want to build from there.”

But suddenly, I’m like, “Oh no. We need to explain to them what cURL is and how you don’t need to activate an API key. If you get an API key, it’s good to go. You just have to use it.” And we really needed to kind of spell things out for them. So yeah, that was fun.

Code patterns

This is where I give my shameless plug. This particular, well, let me take a step back. At IBM, we write these things called code patterns, it’s our end-to-end solution using open source, IBM technology, a number of other things. And one of the code patterns that I wrote was just, I say just, but it was stringing together three services: Watson Assistant, our chatbot framework, speech to text, and text to speech within the Unity game engine, just to show folks how to get those three services connected and running together.

That was the biggest hurdle that we had. Once we got over that, we could get folks into the SDK, looking at the examples, looking at the documentation, and they could kind of help themselves from there.

But if we couldn’t even make them confident enough that they could work with these services together, they were abandoning our stuff and in some cases, abandoning all ideas of working with anyone’s cloud because they were like, “This is just too hard. I’m overwhelmed. I’m done.”

I’m like, “I don’t want to do that. I want to be a team player.” I want to make sure that maybe if IBM Cloud doesn’t work for them, they’re going to go check out one of our competitors. They’re not going to be like, “This cloud thing is not for me,” and run away because that’s not cool.

So I ended up building this code pattern, and you can throw tomatoes. It was originally written only for iOS. I have since updated it. It now runs for Android but it’s because I didn’t have an Android.

So, now folks are able to go out, they poke at that, they hack that to bits, they show me what they’ve written. It’s been really, really cool to see what folks do because it’s a very, very basic pattern in my mind, but it got folks over the hurdle of connecting those services and fighting things, which I thought was not something that I had to do.

Figure out who is using your docs

So to wrap up, some things I want you to think about, because maybe you’re not working with enterprise developers, maybe you’re not working with game developers, but you are working with developers. So, what I want you to do is figure out who’s using your docs today. Are they getting what they need? And are you agile? I think we’ve heard it earlier today. Consider adjusting those personas as well.

Did you cover the basics? Did you make sure that you covered the basics? And did you make some assumptions that could alienate groups? And to kind of go to my one-size-fits-all analogy, I could definitely wear a XXL shirt. I don’t, but I could. Because it would fit, like I could wear it.

But just like when we’re thinking about our developers, if you throw the documentation at them, yeah, they could probably work through it, but are they really getting what they need? Is it the most efficient use of their time? Does it make them look the nicest? Does it make them feel confident?

And I would argue that a XXL t-shirt is not going to make me feel confident. So, thank you.

Leave a comment

This site uses Akismet to reduce spam. Learn how your comment data is processed.