December 18, 2014
How Great Documentation Drives Developer Adoption
Using examples from Stripe, Heroku, and Django, Jacob discusses what makes for excellent documentation -- who reads it, who should be writin...
Thank you. I had promised myself not to build a bunch of slides, and then I found myself building a bunch of slides. I'm going to just go through them, and then feel free to jump in. I'd love to just see what specific developer community needs you have and how I can help address them.
So, quick slide about me. My name is Tamao. I've been doing different types of developer community building at companies such as VMware, Pivotal, and most recently at New Relic. And then currently, as mentioned, running DevRelCon SF, which really was just a small volunteer experience and has grown into something else. It looks like it might actually happen again next year.
For VMware and Pivotal, my background was really working with open-source developer communities. I primarily was supporting Cloud Foundry, Spring, some Groovy/Grails. I know Gradle's here, RabbitMQ, and some Redis.
At New Relic, it was definitely more about supporting developer communities for the product that New Relic had built, but it is around different agent languages. So those were really focused on getting street cred with the communities around those languages: Java, Python, PHP, Node, etc. I wanted to share a little bit.
In the last couple months, I've had the really great opportunity to talking to so many different kinds of companies, really small, like one-to-five-person to really large, or building on a new area. And it's just been so eye opening to hear what their business challenges are, what they think their developer challenges are and what they need to solve.
So many of them have come to me like, "Hey, I want to talk to you because I really want to build a community." And sometimes by the end of the conversation, I felt like I was almost convincing them that it's important to build a community. But let's step back and see what your needs are and see if that's actually the primary priority for now, because you might have other things that you need to work on first.
My first thing is, part of the reason that my friends got together to build DevRelCon, is that I felt a little bit frustrated by now. There's growing talks and opportunities to hear expertise, and some areas you hear talks where they just say, "Okay, you want to build a community. Do this." Right? Or do that, and so many of the answers would be different based on what kind of community you're trying to build.
Are you building a community around an open-source project that you built? Do you have developer tools? Do you have a platform with an API? Is it like a partner ecosystem? Or are you just selling a product? Or many other scenarios.
The answers are going to be really different, and your priorities are going to be really different, depending on what you're trying to build your community around.
And then also, "Where is your open-source project?" or "Where is your company in its maturity?" There's really never one answer, so that was one of the things we're trying to address. And why? Why do you think that you need a community?
It's been really great talking to a lot of different companies, because they'll have a lot of ideas on why they think they need a community. They need to grow their customer base, or they feel like there's so much work to do, and maybe they can find community members to help out with that. Or maybe they also need validation within certain communities. Or they need champions that can give them the validity that they need to speak to those particular communities if they don't have that kind of technical expertise in that area.
An example might be, "We've built our original product. It's really well received in the Java community, but it's just as usable in the PHP community. But we don't really have that expertise there." So, if you can find that one champion who's well known and well respected in a PHP community, who says, "Oh, I love your product" or "I love your tool," they can speak on your behalf.
In some cases you might have regional reach. You suddenly have these surprise communities that show up in a country that you hadn't really had the time to think of. But now you have to figure out, "Do we localize? Can we afford it? Maybe we can depend on the community to help with that." There's so many different reasons. And sometimes they'll be prioritized and sometimes not.
When I have conversations with companies, and this obviously will get to what's finally going to be around metrics and ROI, I ask what are the top two needs or pains that your company is feeling, or that you as a leader of your project is feeling. And so they can be like an open source like, "We really need to develop this, but I need people to contribute, and I really need help with that."
Or we need validity by having tons of users being happy with it and talking about it and feel like this language is really taking off or this framework or whatever's really taking off, and it's becoming, I don't want to say "standard," but it's become really popular. And then if you have a company, what are the top two needs around the value of the company in terms of revenue or longevity of the company?
You don't want to just sell it, you actually want it to have a life that's long.
And so with those you'll probably have primary top needs and pains that are around increasing your revenue, maybe beating your competition. You're afraid that they could be coming up with better features or with better tools, or maybe they have better marketing. Ultimately also being able to innovate and make sure that what the company offerings have will sustain the life of the company with more meaningful offerings to the company.
So those might be some examples of top needs that your company or your project might have. So the question is, when you're thinking about, most of the time, instead of talking about the context, most of the time people come to me and they go, "Okay, I need to grow a community." Or, "I need to start a community, what do I do?"And so with those I ask first, well, what are the top 10 goals? And then, is the community a priority?
Sometimes you might say that you are ready to start building that. You got a surprising uptake in interest. You might have really hit upon a particular technological need or tool need, and people are really picking up with it. So that would make sense, but in other cases, you might have other headaches existing, like your engineering could take down your product for three days and really break down your credibility.
That might be a better focus, or you're building an entire platform that has all these different pieces to it where you need to create a better feedback system first to understand where to prioritize, before just saying, "Okay, we gotta build this developer community. We gotta make sure that they're happy."
Moving forward. So, of course, who is my community? That's the other thing. I don't think I'm the first to say this. A lot of people say, "Oh, we gotta reach out to developers." Well, there's so many different types of developers, and I'm sure you know this, but some of the things to think about, like what languages are they using? What interests them? What are their needs? What kind of culture do they come from? And how much time are they able to give?
There is one, and this is the area that can be kind of sticky because there are going to be stereotypes and some of the stereotypes work. I think it was in VM where we had talked about if we can only focus on two main demographics, what would they be? And we had this slide that made us laugh, but it was often true. It was sort of around 30, 35 was the breaking point in age.
So you had groups of developers who tended to be under 30 or 35. They tended to not be married yet or have kids. They tend to be in urban places. They love hackathons. They've got plenty of time on the weekends. They love going to meetups. They have plenty of time on the weekdays. They might work with more dynamic or easy-to-work-with languages for getting something quick and running, maybe like Ruby or Node.
They'd be interested in different technologies, and then there's the other stereotypes, of course, was the over 35. They've got families; they don't have a lot of time. They might live in the suburbs, but they still want to make sure that they're up as much as possible with the latest technology. And so with each of those there are various choices of language. And I forgot to mention, some of those might be tending to use Java or .NET. So there's different areas.
With each of those areas, you'd have to think, well, who are the main users of my community? What would their needs be? And what is our likelihood of finding that engaging with your community is very valuable to them? So again, I think it maybe obvious, but some people haven't heard some of those general areas of focus.
When I was talking to different people, often it focuses first on what we need. We need people to contribute code, or we got all these questions in our forum. Or we're getting all these support tickets and we can't sustain all of them ourselves, so it would be great if we could start creating an active community of people who can get engaged, and we can create campaigns to incentivize them to help.
Of course documentation is incredibly important to make sure that you have a smooth and positive onboarding experience for anybody who's either going to use your tool or going to use your product. You need help with that.
Again, the regional parts, we need people to translate. Or we need better SEO, we need content, we need blogs, or we need to write our own blogs. We need guest bloggers, and then just getting out there at conferences and speaking. Ultimately, hopefully, people are passionate enough to create their own user groups.
These are very common needs that often come. And to that, I'll say yes. You absolutely do need a lot of these things. But again, prioritizing those are really important. And they ultimately are tactics that are going to get scattered and become not very useful unless you have them clearly under clear goals and clear strategies.
Those have been some of the things that I've talked about with people and would be happy to chat with people here if you're interested. And again, I should mention I'm not a consultant. I don't do this for pay. In fact, it's pretty much been for the joy of it. It's really great to hear about different people's needs and just giving my thoughts, my opinions on, after listening, whether building a developer community is the top priority.
So of course the other part is a lot of other people really focus on, "This is what I need out of my developer community. This is the reason I need to build them." It's really important to go back to those thoughts that we talked about on who are the developers you're thinking about and what is it that they'll get out of contributing if you're asking a lot out of them?
From that, again, we talked about what are the languages that they use. A top priority of developers is often to continue to build their skill sets. And so you want to make sure that if you're asking for something that you give them opportunities to contribute in ways where they're constantly learning and growing and not just giving them tickets that they have to fix, and then it becomes another job.
In some cases, we've been to some national communities or other communities where they're honest, where they say, "I really love contributing to this open-source community," or, "I really love contributing to this project, or even helping with a product, because my day job really isn't that exciting and challenging, and I actually don't find it really meaningful. But in this community, there's something that I can give back, and I feel like I'm learning, and there are people that I'm connecting with online."
So those are one of the things, too, that I don't feel like it's an exploitative thing. You're actually offering them a chance to work on something that they're really excited about. And sometimes those people end up getting hired, as well, into your program.
In terms of opportunities, belonging, fulfillment, again, these are all part of that as well. People have to balance between their regular jobs, but also they can find something valuable that they'd be getting out of it. So I think you have to think about that when you're designing your programs. Just think beyond what you want to get out of a community: people helping. And think about how they can create a journey. And I'll go into this a little bit more later.
I wanted to give just two examples. You can jump in and share, but I thought it'd be more concrete to create a scenario, show some scenarios, that are conflated of different conversations that I've had, and what conclusions we came to and what ways we thought about success metrics for that.
For example, if you're like a one-person show, and that could be like you're a one-person startup, or you might be a one-person dev advocacy team. In any case, here's a scenario: You have a great technology. You yourself or maybe some key members in your company have very good expertise in that particular area. And then let's say you've gotten fairly successful at getting a good number of users and followers, so people are actually using your technology.
They might be downloading it. They're asking questions. Hopefully, you've addressed the need, and that's why you've started a startup. You feel motivated that it's worth doing it.
And so let's say in the first six months, like one person I talked to, I was like, "So, how's your API documentation?" And they're like, "Oh, I need to get to it." I think that might be a very high priority, especially if you want people to be involved in your new, growing ecosystem, that if you have an API, document that.
Or for example, if you're in a case where you're getting all these support questions and you'rethe only person dealing with them. Or you and a small team are dealing with them. I know that it takes extra time to get those into documentation. But in one example, when I was asked, "Should we build an entire DevRel team to focus?" my guidance was, at least maybe in the first six months, you can get even a junior dev advocate or someone who's aspiring in that area and just get someone who's key.
If there's the same 10 questions that keep coming in each week, just get those documented first, and that dev advocate who's supposed to have some good writing skills, jump in for that and to get that part triaged. And then the next six months can be focused on other types of activities. But that's one of the examples that came up.
And then another example of a one-person show was that we need all these sample apps, because we want to have validity for different languages. So we have sample apps in all these different languages, but it was sort of like a shallow, wide net. And so we talked about some case studies that we'd had in the past where, really, just write one really good sample app or focus on one SDK, and just start with that and really build that story there.
Of course, you're always going to feel like you have pressure to be able to show more or reach larger, more numerous developer communities, but at least in the things that we'd seen, there are certain areas that just go deeper and just stick with that, able to show that off. So that's one example.
For your early users, if they want to try out new technologies and they recognize you for your expertise, that's going to be some of the incentives that are going to bring them to get involved. In some cases, really, you might have developed your personal brand and your technical expertise, so that alone, people are like, "Well, I want to see what's the next project for this person," just out of their curiosity.
If there are open ways that they can contribute back, then that may alone be itself. If you don't have that kind of thought leadership, then hopefully, again, your technology will speak for itself, and then you can draw them in that way.
Those first six months, they can help on the documentation. They can help built the empathy as well, right, because they are both your users and the writers. They're often going to be the ones probably helping with the docs, because they're in and saying "Oh, I followed your instructions, and actually, it completely didn't work." Or, "Actually, one of the examples that you gave me, that I'm supposed to put in, completely broke everything."
Those are the kinds of things when I'm sure you all have tons on your plate, a community member could help with that. And then again, if there's code to contribute, they can contribute.
Just the right hand column, for metrics and ROI, I was just thinking, again, metrics, many numbers, numbers, numbers. How many people downloaded? How many numbers of users do we have? And that's one metric. It's fine. I've always come from the perspective that if you can get the numbers, get the numbers. That's fine, but then what's the bigger story that you can tell, how you aim to have metrics around that.
So really, here, the bigger story is that people had a really awesome experience with your technology, and part of the reason they had an awesome experience with your technology was that getting started was so easy, so seamless, they could get to that "aha" moment, which is what you want.
They could get to that aha moment so smoothly that then, getting a little ahead of myself around champions, that they're going to tell their friends, "This was so great. They understood me. They understood what my needs were, and I'm definitely going to use this technology."
Then from there there might be kinks, and maybe I'll help out with the kinks. But that's the overall metric we're going for. You could have numbers perhaps on, once the documentation was improved, maybe you're able to put a survey through it or you have lower numbers of support tickets. You have lower number of just questions coming in your forum.
Those can be the types of reverse metrics that hopefully are more meaningful than just "these are the number of people who downloaded," and maybe a lot of them trickled off, but instead, how many of them are sticking.
Going back to building that one amazing sample app, is that when I hire for developer advocates or developer evangelists on my team, what I'm looking for are people who can tell a story that's empathetic. "What is your problem that you're trying to solve?"
You know, a specific Python developer or a specific Node developer, or like, "Oh yeah, the latest version that came out, some things are cool about it, but isn't that really annoying that we have to deal with X, Y, and Z?" And "You know, this is how this product or this technology helps with that, and by the way, here's my sample app that can show it off." So, that sample app just becomes an integrated part of that story.
When I'm hiring, I make sure that I have someone who has both the technical expertise and the storytelling capability to tell that whole story. If you are that one-person show, then you kind of have to do that yourself, but hopefully there are ways in which your community members can help in those really targeted ways.
Hopefully those metrics and ROI are more meaningful than just "we went to a number of shows, we wrote X number of blog posts, we blah, blah, blah, blah, blah." But really, what contributed to that story? And hopefully on the backside you have fewer problem questions and more people downloading and using.
I have another example. It might be slightly different for this case, but I thought I'd share it because I did have many different, I won't say clients, but friends, people I talk to who had areas where they intersected on this case, which was where I came out saying, "Well, depending on where you are in the maturity of what you're building, I'm not sure if you actually need a DevRel team, if developer relation should be the focus right now."
In some cases you do, but if you're less mature, it was just my guidance by theations. And that's if, let's say you have a type of platform or marketplace where you have multiple points of connection. You might have end consumers who are actually consuming a product, and then you have people who are building businesses on that platform, and this could be an example of ads, or it could be examples of tools for business building or what have you.
Then you're thinking, "Okay, for this to be a rich and exciting experience for the business builders and the consumers, we need more apps. We need more innovative ways in which those two can connect with each other." So then you build. You have APIs, and then you build your developer communities around them, or at least that's the goal.
In some cases, some are really, really mature. They've built really rich partner ecosystems, the APIs are well documented. And maybe there's some stick relationships as the core company starts changing the rules around APIs. Those are business decisions that might be made.
Building that developer community is one thing, but really creating the feedback loop between the business owners and the consumers was first important.
Some of the cases I heard, "We build these hackathons, or we go to hackathons, and we just want developers to build innovative, cool apps, and then hopefully they'll plug into this marketplace in our platform." And I felt like you could throw this wide net, and hopefully you get one great shot or a couple shots, but I think that that could be very challenging.
If we're going to talk about metrics and ROI, extremely hard to measure. In some of these cases that, like I said, had points that they shared, where they had business owners and seemed like, in some cases, whether it's through surveys or whether it's through different means, there's still so much data that could be gathered there to see what the business owners could give feedback and say, "This is the experience that they're having with my business, thanks to X, Y, and Z technologies." Or, "This is what I think I'm missing."
There are two models that we discussed. One, it's kind of like a car dealer. They're like the car dealers, and they can tell you what their car buyers are looking for and what they desire and all that. So that's one channel of getting information.
Then the other channel of getting information isnow you can go directly to the consumer and you can survey them, and you can get their feedback whether it's their user experience of a tool, a platform, ads, whatever it is. And so that's where we started.
One of the things we said was, "Okay, you have that one good sample app, hopefully it works with this platform. And then in terms of your dev community, it seemed a common area that we saw where certain startups, either they want to leverage the existing platform or marketplace that exists, or they already know certain needs that they've noticed. Maybe they use the platform, maybe they're involved with some of the businesses, so they see those needs.
And then finally, they have the desire to innovate. Instead of doing a broad hackathon that doesn't have key themes, it seemed more strategic to really focus on particular startups who are very business oriented or innovation oriented and they could see the particular need, and they can look at the survey data and address those.
So, you're coming at it from two different directions. You're coming at from surprise innovation, that then it turns out is really successful, to the businesses and within the marketplace. And in another channel where it's like you really are maybe more pragmatic, and you're seeing that there are specific needs that you're going to address with the apps that your developer community builds.
That was some of the things that we talked about, that the startup mentality, the types of people that you're trying to target would be much more strategic to think about as part of your developer community for your platform than, "Let's just do dev hackathon activities. Let's just do this outreach and see what happens."
The final part was if we had a couple examples where there were really established and thriving platforms and marketplaces. Some of the people who were coming on board as startups, if you create a symbiotic relationship where you could share that knowledge, whether it's about business-building, whether it's about building that marketplace, whether it's doing marketing to a new group, those startups would find that as a symbiotic relationship.
This is a little bit more like a partner than just a dev community, but they have developers in there. And so some of the guidance that hadn't been thought of, I said, "Well, if you're asking this of your dev/partner communities, is there a way that you can give back by helping them build their businesses? Because in some cases, they could just be two developers who are really excited and they created this great technology and they want to take it to the next step, but they don't have any business background or marketing background or help. Those were some of the things that came up.
Back to the metrics, you can say how many apps were built. How many apps are being used by businesses? How many apps are being used by consumers? Which is great, that's a couple of metrics that are important to keep in mind. But ultimately, again, what's the full story? And what is the full value that these apps bring to the entire ecosystem? And what, again, is the empathetic experience that the startups can now have by injecting themselves into this platform that also has the business owners and the consumers?
Finally I was going to talk about how now that you created these scenarios, you're going to have your champions, the people who have come on board. They've either followed your one-person gig or they are interested, for professional and for various reasons, to be involved in your platform. How would you leverage them?
It goes back to what kind of developer you're talking about. If some of them want to build skills, think about the professional development that you might be able to offer. If it's the meaningfulness of the work, think about the personal development that you can offer.
When I built the champions program for New Relic, I had gone from, "Okay, we gotta build this program, and gamification keeps coming up as an example, a way to build it." And so I first went from, "I don't really want that, I had a personal reaction to it." I said, "I don't find meaningfulness from that for me. And so I'm unsure about existing champions programs that I've seen, or ambassador programs that I've seen that really get gamified," to doing a lot more research on drive and gamification and motivation as a whole.
Coming around at least to a middle area where the most important thing, I felt, was to make sure that you had a philosophy to your champions program, that's really what's going to drive the meaningfulness and the ability to connect with these different developers that we talked about. At New Relic I really incorporated these thoughts really strongly, and I felt that our champions program would make sure that if you are involved, you are always going to have some level of personal and professional development, because we're on this journey together.
With New Relic, I think the message helped as well, because it's performance monitoring for apps. So a lot of developers would say, "Oh, I never would have found this bug or this problem if I hadn't used the app performance monitoring tool." So I thought New Relic helps you become a better developer, because you're able to address your problems and learn from it.
I made sure that the program itself also had that idea of you can become a better developer by being involved in our community.
In addition to that, a great discovery, and I'm sure this is probably the case with many of you users, is if you see your users, your technical users, you'll find out, "Wow, we actually have amazing people who use our products. They're really interesting people. They have interesting problems that they're trying to tackle, and a lot of them have thought leadership and expertise.
That's where we really work to have them meet each other either online or in person at different types of activities. Because with modern marketing, if that's what you want to call it, you do create content, but you also create the space in which your users create the content, and they create the meaningful word of mouth, whatever you want to call it, exchanges of ideas and sharing knowledge and all that.
Those were the two main tenets upon which I started designing the champions program there, where we just said, "You want to become part of this community because you're going to meet amazing people and you're going to continue to learn. And then through this program, if you do stuff for us, like if you blog or if you run a group, etc., the way that we want to give back is not, I mean, there's always going to be swag and there's always going to be fun stuff, but really the core of it is an intrinsic value.
I designed it so that whatever you earned would be earned in the form of opportunities to learn. And so there'd be opportunities to learn through one of our partners, like a new coding language. New coding language, if it's something that's on your mind, you've earned that. Or if you want to become better educated on just performance in general, web performance in general, obviously we have a lot of experts in that.
Also, New Relic was a place where we were one of the first to use Docker in production, and so we have a lot of that knowledge there. And so we were able to have people learn through our own employees. So there are all these different areas in which we made sure that you had great people on your own team, you had great people among your users.
Just it's connecting them and having them see the value of being part of that champions program. That was the philosophy that I built, and we ran activities around that. And it's just very nascent, and I'm actually not there anymore as of six weeks ago or something like that, but that was something that I pretty much started building from about a year ago, building the philosophy, building the tactic so that all those tactics were under a broader strategy and goal.Thank you.