Relicans host, Ben Greenberg, talks to Developer Evangelist, Lorna Mitchell, about developer burnout, writing technical documentation, and open-source culture and what it can bring into our working cultures and docs portals.
Should you find a burning need to share your thoughts or rants about the show, please spray them at email@example.com. While you're going to all the trouble of shipping us some bytes, please consider taking a moment to let us know what you'd like to hear on the show in the future. Despite the all-caps flaming you will receive in response, please know that we are sincerely interested in your feedback; we aim to appease. Follow us on the Twitters: @PolyglotShow.
Do you have ideas about how we can make our show better? Or would you like to be a guest on an upcoming episode? Reach out to our #devrel team at firstname.lastname@example.org. We would LOVE to hear from you with any questions, curiosities, and/or feedback you have in hopes of making this the best show possible!
Jonan Scheffler: Hello and welcome to Polyglot, proudly brought to you by New Relic's developer relations team, The Relicans. Polyglot is about software design. It's about looking beyond languages to the patterns and methods that we as developers use to do our best work. You can join us every week to hear from developers who have stories to share about what has worked for them and may have some opinions about how best to write quality software. We may not always agree, but we are certainly going to have fun, and we will always do our best to level up together. You can find the show notes for this episode and all of The Relicans podcasts on developer.newrelic.com/podcasts. Thank you so much for joining us. Enjoy the show.
Ben Greenberg: Lorna Mitchell is based in Yorkshire, United Kingdom. She is Head of DevRel at Aiven as well as a published author and experienced conference speaker. She has a strong background in open source and a passion for better developer experiences for developers everywhere. You can find out more about Lorna on her website at lornajane.net. Lorna, welcome to Polyglot.
Lorna Mitchell: Hi, thanks for having me.
Ben: It is so nice to have you. I was recently on a plane on my way back home because that is the story of so much of developer relations, on a plane somewhere. And I was reading a recent article you wrote in TechCrunch around improving mental health for developers. And I absolutely loved that article.
And so much of what you wrote in that article really resonated with me, specifically around when you talked about burnout, and what causes burnout, and how we can help mitigate against burnout. And I wonder if you could share some of those insights with us here on Polyglot.
Lorna: Yeah, let me try and summarize. It's definitely a topic that's really close to my heart, which is why you see me writing about it and on TechCrunch, which is amazing. I think burnout for developers for DevRel as well is we can do amazing things. Like, humans are incredible, and they have untold depths. When you really believe in something, isn't it incredible what you can do?
And I feel like burnout is the opposite when you don't really believe in it, or you're really dragging yourself or being dragged through something. So it's about conflict. It's about there being too much of something that you don't want. Sometimes it's too much of something you do want, and we see that particularly in the startup founders burning out. They literally just burn everything they have to chase their dream.
Lorna: For me, that burnout piece is about taking care of yourself and realizing when something is happening, or something is changing that it is time to look after yourself. And I think this is something that we should be better at as technical professionals.
You don't wait till the disk is 99% full before you upgrade [chuckles] to new storage. You set the alert level at 80%, and you get a new disk. You deploy it to a bigger cloud or whatever your setup is. So don't wait until you're absolutely broken because the roadmap from there is long.
Ben: So how do you know when your disk is getting to 99% full when we're talking about burnout? What are some of the cues that you've seen in others or maybe in yourself that says, "Wait, hold on a moment here. I think I'm approaching a crisis moment." And what are some of the signs, and what do you do to help address those?
Lorna: The signs are, for me, it's definitely negativity. I mean, it's all right to be grumpy once in a while. But if you're grumpy four days out of five, something's wrong, especially in something like software development or developer relations where really, we are doing what we love. We are chasing our dreams. And so when that's gone wrong, I think that's one really big sign.
I'm remote from my team, and I have been for more than a decade in all sorts of different types of jobs and different employers. And you have small children; you’ll know this; when it's too quiet in the other room, and you suddenly hear the silence, and you run through to find they are cutting up something.
Ben: Something is wrong when it's too quiet.
Lorna: Yeah, it's too quiet. It's a little bit like that that you don't get the same engagement on the virtual channels. It's harder to tell when you're not in the office. You might see someone leaving early or coming in late or just looking a bit rubbish.
And I think for remote teams, this stuff is harder, but it makes it more important that we look out for those signs in each other, in losing interest in hobbies, being less present at work, always being negative. Like, let's talk about it.
And I would rather reach out to someone and then think I'm a lunatic for deciding they had a problem that didn't exist than not reach out to someone that I could have given some words of support to.
Ben: So being overly proactive in your support and care for your colleagues because that proactivity might not hurt, but it'll definitely potentially help if they're actually in a crisis situation.
And I think what you said is particularly prescient around when we actually really love what we're doing, when we care about what we're doing when we're passionate about the things that we're working on, that's when the challenges of burnout can become even more pressing in many ways. That's a really, really good insight. Thank you.
And you also in that article, you talked around...so we work in code, we're working in software, whether we're working in core engineering teams or working in developer relations. Our lives gravitate around the cycles of software.
And you talked about open source, what that culture of open source can come and contribute to our teams, whether our developer relations teams, our engineering teams. How does the culture of open source lend insight, and what kind of insight can it lend to our working teams?
Lorna: I think increasingly, we are remote now. And if you think about the things that have been built in open source by people who not only have you never met in person but may only know one another by an IRC handle, mailing list, my mind is slightly blown. I look at the number of meetings on my calendar for things that really are not Linux, [laughter], and I wonder why we're not better at this.
I think the open-source practices of always logging the bug in a formal way, giving a description that somebody else can use to replicate without needing to go back to the original author. My projects, a lot of the reviewers will have merge access. I expect the reviewers to merge. Don't wait for the author again.
So it's about asynchronous work and trust, giving all the information but also the permission and passing it forward so that everyone can do their best work in turn. And this is important across time zones. It's important across open-source projects where people are not available on a regular schedule. It's maybe your Sunday night. I ran an open-source project for years on purely the occasional Sunday night blitz.
Lorna: And you can do a lot. And I think our developer relations is a bit like that because the interruptions of conference season mean that we are, as I described to my office-based colleagues, very unreliable. Because you'll find the wrong month of the year the whole team is gone for three weeks. Don't talk to us. We are fundamentally not here.
Lorna: And so being able to set those tasks up and to be able to jump in and make a difference with them at the right time is really important. And I think that's what comes from an open-source culture, which is very respectful of everyone's time because they volunteer.
Ben: If you take a step back, what you said is absolutely astounding. You look at what has been created over time to this very day and continues in that culture of open source without anyone maybe even knowing each other's full names, not living in the same geographic proximity, not having back-to-back Zoom meetings together. And yet, entire worlds of open source that we all rely upon have been created in this culture of, like you said, accountable, empowered, open-source.
So it sounds like to me one of the things that people can do is be very intentional in their asynchronous communication, describing things in a way in which that person who's describing it would not need to be reached out to again for clarification unless absolutely necessary. But because they've described it so well, that the work can continue, and trusting and empowering built on that foundation of intentional descriptiveness, intentional accountability. I think that's absolutely profound. You're totally right.
Lorna: How I try to work with my team is I how try to build things with other people. And again, they might not be full-time. I mean, it is my team now, but this is my first time really officially being in charge. And so the rest of the time, I've just brought people along with me and tried to get people to buy in as a side project or whatever. And you have to respect people's time. And it lets us do our best work, in my opinion.
Ben: So what ways are you doing then now at fostering and cultivating that culture now that you are the person in charge? The buck stops with you, Lorna. So in what ways are you doing that in your team?
Lorna: Well, it's brilliant. I just tell people what to do, and they do it. [laughter] It's like playing the game on easy.
Ben: You just get to do it, and that's it.
Lorna: [laughs] Yeah, I just assign things to them, and they do it as opposed to having to gain excitement around the project, and tag issues, and ask people nicely or whatever, and that still happens. The big project that I'm working on at work is our new docs portal, and the whole company has input into that. It's very much like an open-source project. In fact, it is an open-source project because it's a public repo as well.
Ben: So, our listeners, we will link to the public repo for Aiven's new docs portal as well as the article on TechCrunch in the show notes once this is published. But talking about the docs portal, it's a great transition because I was looking at that codebase just a few days ago. And you're doing some really interesting things there.
And I know you have a lot to say about docs as somebody who has thought deeply about what docs mean for developers. And I think we have to start at ground zero, which is why are docs...why is documentation important when you're thinking about developer tooling and developer products?
Lorna: I think that docs...it's entry-level. We know from the recent surveys...the Stack Overflow survey and the GitHub State of the Universe both, I think threw this up as well that people really expect docs, and they rely on them. All of us are new to something sometime.
And for developer experience, there are lots of things we could do to make things easier. But writing things down is the number one way. It's not the coolest or the most glamorous or the most high-profile way to convey information. And we work in developer relations, and we're famous for all sorts of...we're both streamers and whatever.
Lorna: When you write something down, that content can be searched. It can be discovered by machines. Someone can read it; it can be spoken out loud, it can be translated, it can be read with high contrast. It can also be read by someone on the other side of the world. It's low bandwidth. It can be read in a hurry; someone can search for the keyword on the page.
It can be read for years from now when someone else is learning the cool technology that I'm excited about today. They don't have to find me giving the talk or find the recording. The information is there. And it's just there to support them and to help them along the way.
If you don't have documentation, there's no point in having a product because people can't use it. You're not enabling the developer experience if there's nothing there for them to understand and get started with. I've been a writer for a long time, but I'm super passionate about documentation as such an important part of any developer-facing product.
Ben: Sounds like documentation as written documentation serves as the foundation stone for everything else you build on top of it for all the reasons you enumerated.
Recently, I was speaking to somebody who was telling me that...and this is an angle I had never really considered, but this person is not neurotypical. And they said that written documentation for them allows them to process the content in their own time and in their own unique modalities.
Whereas if I'm presenting to them in a stream or in a YouTube video, I get to choose how I present it, whereas, in the written content, they can consume it in the way that is best for them. And honestly, I had never considered that perspective either until that person said it.
Written content not only is it evergreen for good and for bad sometimes, and it's stable, and it's searchable and indexable. But it also allows the consumer of the content to consume it in any way that they need to consume it without you deciding how that should be consumed. So you start with reading content when you're beginning your documentation for anything you're working on. And it hearkens back to your open-source history.
Lorna: Yeah, I think so. And I think that kind of low bandwidth, high information, the written content is also easier to have reviewed, to have additions, to have updates in a way that your conference doc or your recording isn't going to.
Don't get me wrong, I like to publish video, and it's something that we're also working on at Aiven. But if the content is not written down, it's like, pics, or it didn't happen. You have to be able to find that in written form with your favorite search engine in the moment that you need it.
Ben: Something I think about also is I'm sure Aiven has different audience personas, including junior developers who are just starting out and staff level of senior-level engineers who are maybe looking for an entirely different picture. How do you build documentation, or where do you start when you're building your documentation that addresses those different needs of different developers along their learning journey?
Lorna: The thing about developers is they're very good at finding their way around. I'm stereotyping, but they're smart, and they are resourceful. So as long as you put all of the resources out, they will typically find things. We also have an excellent search box and all the best structure in the world.
Lorna: Developers just use the search box. I worked really hard on this navigation structure, and you don't care. And that's fine. I'm good with it. The way that we approached it at Aiven...and our developer portal developer.aiven.io is a greenfield project. So it's not been live very long, and it's still a little bit under construction.
We used existing best practice. So we took the Diátaxis framework, which came originally from Divio. You might know it also from the Django docs project. And it uses some very distinct content types that put the user front and center and thinks about what it is that the user is trying to achieve. So the content types of things like reference, looking up information, learning about something.
So if you don't know what, for example, a PostgreSQL connection pool is, you can find out. And then if you need to set one up, then there's a separate piece which is like the task for that, which will link back to the explanation. But if you're already a senior and you know how to do it, then you feel like you're in the right place. And you could just go ahead and follow those linear tasks in that type of content that matches your need today.
So we really built on that existing model, and I think that has helped a lot also for consistency. This is the work of hundreds of hands. [laughter] And so there isn't one person keeping a strict voice on it. We're just keeping things consistent and trying to put it together for everyone that needs the information.
Ben: So the different types of content are connected. But in some ways, they're modularized so that if I don't need the explanatory text, I can get right into the nitty-gritty of how do I do it? But if I need the explanatory text and I may be a senior developer, but I may not have been familiar with this concept, whatever this concept is, I can easily find that explanatory text if I need it. Am I hearing that correctly?
Lorna: Exactly that. So there's like, I need to do a thing. And remember, no matter how senior you are, some of these things will be things that you need to do on a production database in an urgent manner, which I don't know about you but makes me stupid. [laughter]
So we try and make it absolutely clear, here are the steps that you need to follow. Here is where you get your access token; here’s what you should type now. Like, here are the things to be aware of. And we try and just walk you through and knowing that whether you're a new person intimidated trying to learn something that feels big or a busy person with not much brain space, we've all been there fixing something between meetings.
Ben: All of us.
Lorna: Somebody called out at 4:00 a.m. It doesn't matter. These instructions need to be as good as they can be for everybody. And I feel like that is how it includes everybody.
Ben: So I'm curious, do you ever write documentation only for a certain developer for, let's say, the senior developer? And if you do or if you don't, why not? And if you do, in what ways might that be different?
Lorna: I do. I do write for just that senior developer. So you will never see this is how you use the dependency manager. This is how you create a directory. This is how you install Node.js. Because if you're reading those instructions, Aiven's very detailed documentation is probably not the right place.
We shouldn't be teaching you a beginner thing in any tech stack. If you come to us for highly available cloud database services, you probably know quite a lot about a lot. You might not know this thing, but we're not going to start at the beginning of the story because we'll lose you.
And I hope that there's enough there that somebody who vaguely has used Node before could be like, yes, I can go and read the instructions. I know which packages I need to install. So I'll go and read the docs for pip. I need it differently on my platform, so I'll go and look that up. And that's how developers put things together.
So I think it's important for us to keep the scope pretty small for each of the different pieces. And the things that don't belong to us are the beginner things. If you don't know how to write SQL, you are on the wrong documentation site. Then they find their way, and they put things together.
So I've tried to just really keep focus on yes, our main customers are pretty experienced developers who need a platform like ours at the kind of scale that we run it. And I keep them in mind. So yeah, I skip the intro, so you know you're in the right place.
Ben: So it's an assumed knowledge of where you're starting from is, in many ways, a differentiator.
Lorna: Yeah, I try to do that. And I think it really helps people to realize they're in the right place. I am assuming they do know how to use the Redis CLI tool. So it'll be like, you can connect with Redis CLI. Here's the command. If you've never heard of that, by all means, go and look that up. But I am not going to put the install instructions between you and the bug fix that you urgently need.
Ben: That makes a lot of sense. And then they look it up, and then they can come back to you when they've looked it up.
Ben: That makes a lot of sense. Something else I can geek out about a lot with you is docs portals. I love talking about docs portals as someone who's worked on one for three years. How did you come to the tech stack you chose for your docs portal? First of all, what is the tech stack you chose for the Aiven docs portal, and why did you choose it?
Ben: That's a reasonable choice.
Lorna: It's a really short story. I knew that I wanted a markup type text-based Docs as Code-type setup. And if you look, which you can't, but if you could have access to the Aiven private repos, there are some very well structured documentation repos there.
Some of them do have Sphinx; some of them are just really well-organized folders of a markup format called reStructuredText, which is absolutely mainstream in the Python community. And I looked at that, and I looked at who our contributors are, and they're mostly employees. So they're mostly Python developers.
Ben: They're in-house.
Lorna: Yeah. I mean, it's a public repo. So we do get contributions from outside, and I hope that we'll get more over time. So it's reStructuredText; it’s Sphinx. And I also feel like it's really important that when you're choosing tools for an organization, it has to be something that they can be independent with. I hope Aiven won't fire its DevRel team tomorrow. But it can safely operate a Sphinx project given the knowledge that it already has in-house.
The support team could probably fix it out of hours if they needed to. It deploys to Netlify alongside all our main websites. So it's looking at what's the closest thing to what we already know? What's familiar to this audience? It's a bit like DevRel, meeting people where they're at. So although I hadn't used Sphinx before at all, it seemed like the right thing. And so far, I still think it's the right thing.
Ben: I think that makes a lot of sense. You chose the resource that you had the best capability amongst your team and amongst the larger organization for. So that's a very legitimate decision for how you choose a docs portal. Are there things in it that you love? Because this is new to you, Sphinx is new to you. Are there things that you've really come to enjoy using it or something that stood out for you in Sphinx?
Lorna: Something that Sphinx has in common with, particularly the Python community. I came to it for the tech, for the code, but the community blows me away. It's the support. You're looking for a plugin, and there's always a plugin. You log a bug with the plugin, and it's always politely responded to.
People just look out for one another; they help one another. Some random stranger will respond on your issue, and it feels very healthy. So yeah, I could tell you about all my favorite plugins in Sphinx, and that's cool, and these new themes or whatever. But yeah, I came for the tech and stayed for the community.
Ben: Doesn't that say a lot? Because we talked about what makes a great community, and one of the things that makes great software is the community, and that makes us sustainable. I think you're testimony to that, that you've chosen to stay with it because of that warm, supportive community.
Something that I think people don't realize is you have had a bit of an incredible journey to the place you're at right now. How did you end up being in the role you're at in Aiven? What was that like? I'm sure you could write an entire book on that journey. But if you can encapsulate how you are where you are right now, how did you end up there?
Lorna: Well, early in my career, I was a software developer for a really long time. And then I was freelance for a while. I was delivering some training. I was on the conference speaking circuit.
Now, I was only on the conference speaking circuit because I love to learn things. But conference tickets, if you're a junior or a mid-level developer, are totally out of reach. But they'll give you a ticket if you give a talk. So I was like, barter for your own knowledge.
Ben: [laughs] Incentivisation right there.
Lorna: I know. So I learned to speak at conferences, and I did a bunch of stuff. When I was freelance, I also wrote a couple of books. I'm an O'Reilly author. And so you look at all those things. And I was running my own business. I did a bit of technical project management. What does it look like? It looks like developer relations.
Lorna: And so I've been in DevRel for a little bit over five years. And I've done a bunch of different things but essentially databases and APIs. And I write, I speak, and I code. So really, a software engineer is really a back-end sort of scripting person. But I absolutely love to write.
And I'm a very accomplished speaker, which says I'm good at it. But I don't love it in the same way that I love writing. But it's the most high-profile thing I do, so I'm well known for it. But I really feel like the writing is me, and it makes the biggest impact. And it's the thing I'm the most proud of.
So I came into DevRel. I've done a few different things within developer relations. I've built a couple of libraries for different things, or I've published some packages, published quite a lot of integrations, given a bunch of talks. I've worked on a couple of docs projects as well. And when I came to join Aiven as to found the developer relations team, I joined as an individual contributor. And they hired two of us at the same time. But that was nearly a year ago.
Partway through the year, the question came in, "Would you be prepared to run that team?" So today, I run the team, run the strategy, do the hiring, look after the budgets, run the technical blog post content process, run the developer portal. And as you can, I imagine, Ben, because you've worked with me before, interfere on a bunch of other things that I think developers need me to advocate for them about.
Ben: [laughs] Interfere is not the way I would put it.
Ben: I would put it that you have a way to find your voice being an advocate for people and the community across all the different sectors of the organization. And you don't feel constrained by your role to do so. Wherever the developer community, wherever developers' voices matter, you will be in that space. As someone who has worked with you firsthand, I can attest to that.
It's interesting to me. You described all the different things you do. But you do so many different types of work, a multiplicity of kind of content types and areas of work. Do you think that helps you manage going full circle? Do you think it helps you manage longevity you have in a place and your sustainability of that role for you?
Lorna: I hope so. I've only moved into this management role during the year. And I'll be honest; I’m still finding my feet. As an individual contributor, I think the range of skill sets is amazing for two reasons: one is content reuse.
Yes, written content is the foundation stone. But there are lots of reasons to publish in other formats, to reach other people who prefer a different way. And so being able to write your own demo, and then write the docs, the landing pages, give the talks, record the videos, and whatever else and then hear the feedback from people.
If you publish whichever library for an API and then you go and demo it, and someone complains to you, then you're really in touch with those people. So I really enjoy not being siloed for a DevRel role. But also, the variety really helps.
I often talk about the seasons of DevRel, which are certain times of the year, we're difficult to get hold of because all of the events are in the second week in October for reasons that are still unclear to me after ten years.
Ben: Just to keep us in the air all the time, basically.
Lorna: Yeah, but then you find sometimes in the year you can go four or six weeks with no travel because there are no events. Now, why is that? And it's a bit different between geographies.
But I've come to think that the skills and the moving of the seasons, knowing right now we're doing a massive...the biggest piece of the docs migration is happening now in my team because we're all on the ground until the end of January. And that's like, boom.
Ben: This is the time you're all present.
Lorna: It's the winter season. Other people think there are holidays and disruption to work schedules. They're actually the least disruptive times. December is the right time to ask developer relations to do something.
So I think that difference in skills but also the constant changing of the tides has really helped me with my longevity. And because it's quite flexible often, you can choose what you work on. If you have writer's block, there's always a bug to fix in a library. Then that has helped me to find the balance. The week that we moved house, I was incredibly, incredibly stressed. And I wrote almost a whole PHP database library. That's how my brain works.
Ben: That sounds like a perfectly suited brain for developer relations if I say so myself. [laughs]
Lorna: I like it.
Ben: That's amazing. As you're now shipping a whole chunk of the docs in what others call the holiday season, but DevRel calls the busy time for getting work done, how do you know you'll be successful? How do you measure yourself with documentation?
Lorna: Yeah, this is a really tricky one. And part of the problem could be opportunity. With the Aiven dev portal, it's really new. So I don't even have a baseline status, really.
Ben: You don't have a baseline. It's brand new.
Lorna: It hasn't been live that long. So we're migrating content off an older site that didn't really have content design but has really, really good information, just the format's a bit hit and miss, and some of it is outdated.
Ben: Well, that's a problem as well.
Lorna: So being able to grab that and read old docs and try stuff and then produce new instructions or new resources that fit the new world.
Ben: So you're running through the old docs as you're doing it.
Lorna: Yes. So it's like a big migration; all the screenshots need updating and everything. You know Aiven has 9 or 10 open-source data products on its platform. I'm getting to know all of them.
Ben: [chuckles] In this process.
Lorna: It's like the best study ever. So yeah, how are we successful? I mean, getting the migration done is a big one because there are lots of new resources that I want to build. But because we're now in the middle of the migration, we're confusing people by having stuff in multiple locations.
So the initial set of success is...in developer relations, we'd call this activity metrics. Like, is a thing done? I would like to move it forward to be did people find what they were looking for? How many searches didn't return anything? Or how many...we've got feedback, and it's a public project. So GitHub issues for why don't you have this in Java, and those types of things are further down the line.
I think our success will be measured by do people contribute to this? It is a community project. We know that we have awesome, active community members at Aiven. Is it something that we can all work on together? Do our colleagues contribute, and do they find that easy? Because advocacy is so often internal, enabling what happens inside the company.
So yeah, there are a lot of things there. The documentation is not part of the funnel. We report to marketing. So I get into some hilarious meetings where I'm like, no, that is not what is happening here. And so yes, maybe clicking through, but I always think it's more important that people click through from the web interface into the docs to learn something. I would rather see that than necessarily going the other way into the product.
Ben: Than the other way. I think that's a really good perspective. And I also really like how you said that your goals will move as the project matures. And what success looks like is going to change through the lifecycle of the project.
Right now, you're managing the liminality of being between the two different platforms. And it's trying to figure out how successful you are and keeping your users not utterly confused between the old and the new.
And then what you said at the end where I might manage and look to manage some metrics around community engagement with the docs. And are people contributing? I don't think a lot of places think enough about that, what that means, that I have something out there in the open. Is the larger user base running Aiven? Is it actually using it or not?
Are they bringing back into it their shared learnings, their frustrations, and how they overcame it? And maybe in this doc, if you wrote it this way, and raising an issue or raising a pull request, or what have you. I think that's a really good and, I think, fascinating metric to actually ponder on for a little bit as well. Amazing.
Well, Lorna, I want to thank you for your time. This has been a journey through burnout, and through documentation, and talking about open-source culture and what it can bring into our working cultures and docs portals. It's been wonderful. Thank you so much, Lorna, for joining us on Polyglot.
Lorna: It's my pleasure. Thanks so much for having me.
Jonan: Thank you so much for joining us. We really appreciate it. You can find the show notes for this episode along with all of the rest of The Relicans podcasts on therelicans.com. In fact, most anything The Relicans get up to online will be on that site. We'll see you next week. Take care.