Kate Mueller: [00:00:01] Welcome to the Not-Boring Tech Writer, a podcast sponsored by KnowledgeOwl. Together, we explore topics and hear from other writers to help inspire us, deepen our skills and foster our distinctly not boring tech writing community. Hi, I'm Kate Mueller. In today's episode, I talk with Lorna Mitchell. Lorna is a technology leader, published author, tech blogger, and developer experience expert who is passionate about APIs and developer tools. We talk about why developers writing docs is good for both your devs and your docs, and the best ways to build successful collaboration with developers. Welcome everyone! My guest today is a woman who I first discovered through a 'write the docs' talk, who made open API and API documentation actually makes sense and seem like a reasonable form of documentation. And as somebody with no background in API stuff, I figured, you know, if I need to interview somebody who qualifies as not boring, anyone who can make API docs feel not boring feels like someone I should have on the show. So I'm very delighted to welcome Lorna Mitchell to the show today. Hi, Lorna. Welcome.
Lorna Mitchell: [00:00:54] Hi Kate! That is a great intro, thank you so much for having me.
Kate Mueller: [00:00:57] You're welcome. I'm sure you never thought you'd be starting off thinking, wow, what a compliment to be called 'not boring'. But here we are, welcome to the pod. For our listeners, I came from the writing world and accidentally ended up in tech and have ended up writing a fair amount of software and product documentation and a variety of other things. But for me, that was always like an accident. I just sort of ended up here and it's worked. My sense is that you've had the opposite experience, where you started more on the tech side and have accidentally ended up writing some documentation sometimes. Is that true?
Lorna Mitchell: [00:01:35] I think that's a really good reflection. I've always liked words, but I have worked my entire career in software engineering of one kind or another. Along the way, it always seems to be, I've been in charge of multiple docs platforms, and there's a thousand posts on my blog, I wrote some books. This technology thing is amazing, it's easy when you know how and I just can't stop telling people how.
Kate Mueller: [00:02:00] It's a good problem to have. One of the things I've learned is, if you are really excited about the thing you're talking about, people will show up and listen to you. I don't understand how this happens. I've done these half hour sessions at KnowledgeOwl, walking people through new features or whatever. People will be like, I love listening to you talk. I'm like, why? Why do you love this? I mean, it's great, I'm happy you showed up. Here I thought I was just talking into the void, and here we are. Can you talk a little bit about your technical background then since it's, I'd imagine, a little different from a lot of our user's?
Lorna Mitchell: [00:02:43] Yeah, definitely. Actually, confession time, my degree is in electronic engineering, so I'm actually not at all qualified to do what I do. But along the way, we did a bit of software. This is back in the day, obviously I have been doing this for a long time. Maybe you can't tell on a podcast. Anyway, I have been doing this quite a long time. My first job was in software. I wrote games initially, which was a lot less fun than it sounds. It's not the most humane end of the industry, and I have worked in a bunch of other different technical disciplines. I've mostly been in open source, mostly as a back end developer. I also have some accessibility needs. I acquired an arm injury, it's just a horrible tendonitis, in a workplace quite a long time ago. Although my background is in PHP and web development, I became an API specialist because I can't work the front end dev tools. Those all require a mouse and I am keyboard only and I have been for a really large number of years. I'm API and data specialist kind of by necessity, but also this stuff is amazing. I've worked a lot on making computers talk to each other. The humans should not have to take the information and put it in again somewhere else. This exists in the world in digital format, make it happen. In the time that I've been doing this, we've gone from overnight batch jobs to real time streaming data integrations. I have worked on all of that and everything in between.
Kate Mueller: [00:04:22] Wow, that is quite the career and personal life arc. This makes me feel so much more normal because mine has also been equally, how did I get there from here? Actually, it made total sense at the time, but here we are.
Lorna Mitchell: [00:04:38] If I'd ever had a life plan, none of this would have happened. From each place, you just have to take one more step forward. The overall map looks a little bit winding, but I think everything is part of the picture.
Kate Mueller: [00:04:52] Nothing like ending up being an accidental accessibility advocate along the way as well. Plans you didn't expect. As somebody who developed a chronic illness four years ago, totally feel you on that one. Being like, that's a curveball I didn't expect to have to accommodate into my workplace, but here I am. I personally am super uncomfortable calling myself a tech writer or a technical writer. I've never really jived with that role or title. Really, I wish that this podcast was called the 'Not Boring ___ Writer' so people could fill in the blank on how they describe the kind of writing they do, or how they view the documentation that they're doing. What role or title or descriptor would you use to describe the kind of writing that you have ended up doing?
Lorna Mitchell: [00:05:39] I've held a bunch of titles in my documenting life. Most recently I've been VP of Developer Experience. People can't have an experience if they can't use your tooling.
Kate Mueller: [00:05:55] You hear this, internet? People can't have an experience if they can't use your tooling.
Lorna Mitchell: [00:06:00] Build it, but if you're not going to build the docs, you don't actually need to build it. Because if no one can use it, it's irrelevant. So to make your stuff relevant, you need to write things down. A lot of dev-ex roles also are internal to companies. Mine was more external working for a dev tools company, but a lot of them are internal. If you're managing technical change, implementing tools at scale, all of that needs that kind of writing. Do the right thing, write it down. The less you have to write for people to get there, the better. I see it as a very multiplying, enabling thing. I think if I was perhaps born a generation earlier, I'd have been a teacher. I'm like a multiplier, I like to get things down. How did it begin? I've always had a technical blog. I have been doing this career long enough that your computer was not connected to the internet, and I would lose my useful scripts directory every single time I change jobs, and I started putting it on a public blog so that I could use it, other people could use it. The first posts on lornajane.net are from 2006, so I have been telling people things for a really long time. I've also written a lot as, technically, a head of developer relations, as a developer advocate. I've owned docs, platforms and all of those job titles, but honestly, software engineer. I have written a lot of docs, and there's an illusion that developers don't write docs. Maybe that's something that other people do, but actually senior engineers write a lot.
Kate Mueller: [00:07:39] Particularly senior engineers who don't want to have to be the person that gets woken up every time somebody has a question about a simple thing. That if they documented, they wouldn't be the person that you go to for that. In that broad scope of types of documentation that you've worked on, are there any principles for docs that have helped you in that? You've been doing this a long time, you've come to a place where you're like, yes, I recognize that these are the things I care about when I'm working on docs. Or, since you do come from the software engineer world, from the docs that you have to engage with when you're using a tool or a platform or whatever, what do you appreciate?
Lorna Mitchell: [00:08:23] I appreciate the sense that whoever wrote this had a purpose, and that's for me as a writer as well as a reader. Who is this for? What do they need? What do they have? What are you supplying? What do they already know? Because if you start with a really detailed explanation of how to use git, but this is supposed to be for very experienced developers, the very experienced developers think they're in the wrong place, they leave. The beginner developers struggle through this first part, and they can't make it through the rest because it's not for them. It has to be, first of all, having a purpose, but also understanding your audience and having a sense of what that is. Sometimes that means not explaining how to install dependencies in this tech stack. We're assuming that you know how to use npm, next step. I find that, if that's very jarring, there's steps that are skated over and skipped. Then other steps where there's a very laborious explanation of how to create a directory. That really puts me off, and it's something that I see really common around the place, that people are not clear who it's for. It makes it hard for them then to express what they're trying to tell me.
Kate Mueller: [00:09:47] I'm in the midst of teaching a knowledge management masterclass sponsored by KnowledgeOwl right now, and my first class I started off with, who's your audience and what is their purpose? If you don't know who you're writing for, or why they're coming to your talks in the first place, then you're trying to write for everybody, or you're trying to write for this tiny little sliver of, what interests you? Neither of those is going to serve your average user in any way, shape or form. It's a good place to begin with, for sure. Maybe also from a writing perspective, is a lot of the stuff you've done, lornajane.net, that stuff you were writing on your own, sharing with the world, and apparently people are reading it from 2006, which is great. In terms of the docs that you've had to create within the professional sphere, are those things you've been writing on your own or are they more collaborative in nature? How does that work for you in practice?
Lorna Mitchell: [00:10:45] It's been a real mix, although let me say, don't read the lornajane.net posts from 2006. I got better at this in 2008. From there onwards, I would thoroughly recommend. The early ones, you begin somewhere and you don't begin to improve until you begin, so that's the blog story. A lot of stuff that I've written has been collaborative, and that's in two senses. Either each article has more than one person doing the words, or each article is part of something where other people are writing the other articles, but we are presenting it as the product documentation or the project documentation for a thing. Trying to make that so that everybody can do their thing. I have worked with a mix of actual writers and 'really' not writers, and helping everybody to get the purpose to the audience, regardless of the words, because that's, very often, the easy part and has been really interesting. I also do a fair amount that is me being me, and that is usually less for documentation and more for other outlets as a developer advocate and working in developer relations in particular. But also my most recent role because it was a tiny company and you wear many hats. Writing blog content where you can be more individual and sillier than you can in docs. Using silly examples, helping those concepts to click with people and expressing things in that way, and also writing for other platforms. Particularly when I've worked places where, I've been media trained, they've got PR agencies, but it's a very technical audience that we're talking to than writing content for other outlets. Video content and writing for TechCrunch and just different things.
Kate Mueller: [00:12:42] Is there anything you've had to write, any sort of genre of writing that you've done that you really don't want to do again in the future?
Lorna Mitchell: [00:12:52] I was not a good marketing writer, I just wasn't. It's one of those things, I've worked for myself, I'm currently between jobs, so technically I work for myself again right now. It is just not a thing that I am really great at. I don't mind, but I'm conscious that probably somebody else could be doing this, and I could be doing something else. It just sort of depends on that. Otherwise, I think I'm pretty versatile. I enjoy the same content in different formats, and that's true for a speaker. Different talk content and different talk formats like lightning talks, full day workshops, everything in between. Big stage, small stage, tiny audience, huge audience. Didn't do my research, was not expecting an audience this size. All those things. The same for the written content. The detailed blog, the announcement blog post, the docs landing page, the full tutorial and the Readme for the people who insist on arriving through GitHub when there's a perfectly good landing page you've already published. I kind of enjoy that. Different voices, different lenses on the same information.
Kate Mueller: [00:14:17] I mean, really you stretch your style muscles more than anything. It is a lot of under the hood, it's a lot of the same concepts or content, but you're packaging it differently. You're styling it differently to put it out to the world. I would say, for me as well, that's the part of it I actually really love. I think if I was just writing the same content type over and over ad nauseam, I probably would get burnt out really fast. That flexibility to be like, I'm going to write this somewhat snarky blog post, and then I'm going to go work on this pretty straightforward how-to about how to authenticate this particular thing or whatever. Then maybe this release note that's got a little bit of sense of humor, because that's how I like to do my release notes. Then this massive 'Getting Started' guide that is hardcore tutorial, I'm really trying to think about where my audience is coming from and what I need to feed them, and divide that in ways so that people can get into it. Variety is totally the spice of the writing life, I think. I think you do a lot better in the writing world if you're comfortable being like, I can pivot, I can totally write that other thing. I will say, I don't think you're alone in feeling like marketing copy is not your sweet spot, it's certainly not my sweet spot. I discovered that recently working on my own website. I find it easier to write marketing copy for others, but marketing copy for myself? Not good at that.
Lorna Mitchell: [00:15:50] I always have someone else write my bio and stuff like that. This is what we do. I think the other side of that is, as well, having done roles that sometimes did report into marketing in very technical companies, meeting people and working with people who are very good at marketing copy made me realize even more that I should absolutely not be doing this. That is a proper profession and I respect it.
Kate Mueller: [00:16:19] Also, there's something to be said for having the person who's really stoked to write a given thing. What you're going to bring to the table when you're really passionate about a thing is very different than what you bring when you're like, well, I can do this. Is there anything from your background coming up on, what I would call, a much more technical path than people like myself, who came up from the writing side and then happened into tech. Is there anything that you would suggest to other people coming from that developer or engineering background who are finding themselves having to write more, and they aren't comfortable in that space? They were like, wait, I didn't think this was part of the job. Nobody told me I'd have to write, I thought I was just writing code forever, and now I have to write actual words that humans will read? Talk a little bit about that transition and what you would suggest people do if they're faced with that.
Lorna Mitchell: [00:17:20] I think this is a really tricky one, because there's a lot of culture inside engineering spaces, which really doesn't respect documentation greatly. I think if you are a writer, then you sometimes see that play out with a lack of respect for your profession maybe coming out of the more technical departments that you work with. Not every organization, but that is definitely out there. I think we do developers a disservice when we allow them to think that documentation is unimportant, below them perhaps. Somebody else's job, not relevant to their skill set. Genuinely, I think this holds them back in their careers. Maybe you know a lot of developers that don't write docs, depending where you work and who you work with. But if you know any really good developers, you'll know that actually they are really good writers. When we let the developers hold that, that's not my job, that's not important, I'm not spending time on that, I'm not investing in, even reading the 101 on it, I'm not even going to try to find out, how would I do a better job on this? I've read two articles, now I am equipped and I'm going to use those tips in this piece. When we allow them to not even go that far, we hurt their path to being really senior, really awesome developers, being at the top of their craft, because this is part of their craft.
Lorna Mitchell: [00:19:03] If you are a developer, or if you know a developer who might listen to some advice, then taking this thing seriously for what it is, maybe you're not going to be the best writer and it doesn't come naturally to everybody, but all developers, you have to be reasonably smart to do this career in the first place. It's quite formulaic, we've already talked about, who is it for, what is the purpose. Most of the time there's a template, there are three questions you have to answer, and you know how long it should be and if you should link to something else. That stuff is there, so you don't need to become a novelist, but you do need to perform this basic service to your users and to your colleagues and to your future self. Which is where my blog began, the things I've already looked up twice. Want to just read off the page next time. So for people coming in that more technical route, just understand that this is a thing that you can do and it's in your interests to do.
Kate Mueller: [00:20:13] On that note, we're going to take a break and we will be back. Stay tuned for more with Lorna Mitchell.
Kate Mueller: [00:20:20] This episode is sponsored by KnowledgeOwl. If you're looking for an owl-in-one solution to keep your software team's docs organized, KnowledgeOwl has you covered. KnowledgeOwl offers content access control for internal and public docs, flexible customization, robust security, and friendly support. Learn more and sign up for a free 30 day trial at knowledgeowl.com.
Kate Mueller: [00:20:45] All right, we are back for even more fun and even less boringness with Lorna Mitchell. Lorna, up to this point I've been focused pretty heavily on the writing side of things. I'd like to flip the script a little bit here, because it's somewhat rare for us to get somebody who's experienced so, perfectly oppositely, mirrors mine. I'm going to sponge up as much as I can from you as a technical person, as an engineer and a developer. Coming from that side, what have your experiences been like working with formal or explicitly identified technical writers? Have you had them, first of all, and if you have, what have those experiences been like?
Lorna Mitchell: [00:21:32] I've had a mixture of very formally trained technical writers, that is their profession, that is what they do. People who sort of fell into it, but maybe it's just like they're passing through. Then people who are also contributing to the same projects or doing a similar job, but without any of that formal grounding. The first thing to say about technical writers is, you cannot generalize. I'm worried about the title of the podcast. You're calling it the not boring technical writers, are you blowing their cover? They play these boring people at work, they do a job that a lot of technical people must think is really boring, and they're all so interesting as humans. It's like, is it a secret that they are not boring at all? Are we telling people? I don't know. It's been a really mixed bag, and a lot of the time it's been a real good experience. On a very personal level, working with people who actually are technical writers has been a source of great joy to me, because here in the UK, the education system, I think this is still true, but it certainly was when I did it, allowed me to stop writing more than about 200 words at a time when I was aged 16.
Lorna Mitchell: [00:22:54] I have post 16 qualifications in math and physics and engineering and that's it. So I am not really a writer. We don't teach grammar here. I do hold a qualification in Latin, which has helped me enormously, but also a lot of the technical writers that I've worked with are not necessarily native English speakers. Some are, some are not. Either way, this is so interesting because we can all nerd out about words together and things happen. I will be editing something and I'll have to go to the channel where the tech writers live and say, here is the sentence that I started with. Here is the sentence I would like to edit it to. Now explain that to me so that I can explain it to the person who wrote this also using English as a second or third or fourth language. This just sounds better to me. I'm well read, that's how I operate, but that's not useful feedback to your writer.
Kate Mueller: [00:23:56] 'It just feels right' is not useful to help somebody learn how to improve what they're doing, right?
Lorna Mitchell: [00:24:04] Exactly. Why does it matter that this verb in the past hasn't finished happening? It doesn't matter that it was ongoing, but I don't know how to explain that. Having proper word nerds around has been a brilliant experience, just on a very personal level. Working with technical writers especially, there's a breed of old school technical writer who are very certain that there is a correct way to do a thing. They may not enjoy having other people doing anything, especially if it's not done in that correct way. That doesn't gel well with engineering, which is very much like, what's the problem? How could we solve it? Is it better than it was? Great, roll with it, and then iterate. Whereas sometimes that's a very fast and incomplete process. For technical writers who I think are more trained for publishing immutably onto printed paper, that can never be replaced. It's just such a culture clash that, there can be a lot of friction there. I've had that in working with technical writers, like certainly not, that is not how we do things.
Lorna Mitchell: [00:25:22] Looking at how to bring those wordsmiths, but a lot of the time in technical writing, we need the tech writers to be editors. They're not going to write all the words themselves, they're going to make the words be what they need to be and go where they need to go without having control over every word or being the only source of the words. That moving them into the doc's code workflows and helping them to feel confident that these things are for them and for their territory, and work for them has sometimes been a bit of a challenge. The writers that I've most enjoyed working with are people who ask questions, they genuinely want to hear the answer, and they're happy to iterate and keep learning and exchanging knowledge. Keep teaching and keep learning with their technical counterparts. That's been something that I've found very positive in the places where it's worked.
Kate Mueller: [00:26:31] I feel like a bit of what you're describing there, is that you're each recognizing that you have a domain of expertise. That you're collaborating with somebody whose domain of expertise is different from yours, and you're both learning and building a thing together, rather than one of you just telling the other one, this is how it is and how it's done. Is that a fair summary?
Lorna Mitchell: [00:26:56] I think that's a great summary. I think a lot of tech writers are expected to work in that way, where they ask the expert or the engineer to tell them a thing, the engineer tells them a thing, they then write the thing down and that's the only truth that can ever exist. I think that with a bit more crossover between those roles, we can do a lot more together and we can go faster.
Kate Mueller: [00:27:18] I would say in my own experience, most of my technical stuff is, I've worked for small software companies. Usually I've been brought in, I'm wearing 4, 5, 6 different hats, writer is one of them. I'm working with a very small team of developers or engineers who are also trying to do a lot with a small amount of time and resources. For me, approaching that as, all of us have limited time and resources. We're just trying to do the best we can, both by the product from a software development perspective, but also the product by a documentation perspective. How do we do this in a way that hits 80% of a user's needs out of the gate? We feel confident in that and knowing that we can iterate on that moving forward and being less concerned with, I'm not asking those devs to write a final polished thing. What I'm asking them for is, give me a bullet point list of what you think is important. Give me the list of stuff I need to know that you don't want me to put in the docs, but you want me to understand the underlying bits so I can figure out how to structure some explanation that's going to make sense for our audience. Or, take a stab at writing it, but don't actually worry about the style guidelines or linting or anything like that. Just give me what you have and then I will polish it up. Then I will send it back to you to make sure that I didn't misinterpret anything as I was polishing it up. Now I've suddenly changed the meaning on something you put in here, and I don't want to be misadvising people. I think there is a definite give and take there. If both sides can recognize that there should be a give and take there, and that it should be a collaborative effort.
Lorna Mitchell: [00:29:09] Yeah, definitely. I do think developers should write documentation, and writers must aid and abet. We're here to be coconspirators, we're here to make it happen. I say developers should write docs, they definitely should not publish unsupervised, but they definitely can put some information into the process. That's what we need them to do, it's what the users need them to do.
Kate Mueller: [00:29:34] By the same token, I've done manual software testing for a long time, and I've always been like, please don't let me release anything ever. Also, you don't want me testing in prod because I'm good at breaking things. You don't want me being the person pushing code, you don't because bad things will happen. I should not be the one doing releases. I should not be the one signing off on that piece. I should just be signing off on the functionality that I've broken. In the same way that I think a lot of devs probably shouldn't be the one publishing something, but they absolutely should be the one helping make sure that you have created the content that needs to exist for the thing that they built. Let's not even talk about external documentation. Internal documentation, documenting stuff for yourself or for your fellow engineers or developers so that they have an understanding of how that thing works when you no longer work here, or when you're on vacation, or you're on parental leave. Nobody's going to want to bother you when you're getting two hours of sleep at a shot because you have a newborn.
Lorna Mitchell: [00:30:41] Or you just straight up don't remember this thing anymore.
Kate Mueller: [00:30:45] Because you haven't had to touch it for two years.
Lorna Mitchell: [00:30:47] Past you needs you to have written this down, already, last time.
Kate Mueller: [00:30:52] I often joke with my team that the reason I'm so good at documenting things is because I have a terrible memory. They think that it comes from this deeply principled place of 'I think things should be documented', but really it comes from a deeply principled place of knowing that I will forget a thing if I haven't had to use it for three weeks. That's why I write docs.
Lorna Mitchell: [00:31:16] Yes, exactly this.
Kate Mueller: [00:31:18] If I can extrapolate from that a little bit, if you were giving advice to writers who were stepping in to work with technical subject matter experts. Other than treating that as a collaborative effort where you both have room to learn, is there any other advice you would offer to writers in that position?
Lorna Mitchell: [00:31:40] I think one thing that we expect writers to be able to do, but I don't know how we expect them to be able to do it, is to build community, to build that collaboration piece between all the different contributors. This is super daunting, whether you feel that the engineers perhaps outrank you in a company. In many places it will feel like that. Herding those people to be part of a process that they might not be enthusiastic about, I believe that most developers can read, but sometimes it's hard to be sure about that. I try not to accuse them of illiteracy to their faces, but sometimes I wonder. I think for a tech writer to operate that process of getting people to contribute and to be part of it is super hard. For that, you need a really well defined process. Developers are problem solvers, they're very efficient. If they understand this is the goal, this is the best way to get there, they will typically do it. I like to have things like, I have two versions of a style guide in a few places. One for the writers and the more like serious people. Essentially, I've done a ten point list in a couple of places where I've got developers who are not going to read a whole style guide, and that's enough. They understand code syntax linting, so I just throw in some validators with some rules, and if it fails, they just fix it. Run the command to fix it and we're all happy. I've used markdown, lint, veil and tools like that. Super short style guide.
Lorna Mitchell: [00:33:28] Also, if I have a lot of other contributors, which I think is increasingly common in the sort of SaaS type setups, then I try to, and you'll see this if you look back at the different docs projects that I've owned over the years, I think it's really obvious, but really I've moved around jobs, you can still see those footprints in all the different places, but I often structure the doc site in a very transparent, which bits are where. That's for readers as well as writers to be able to navigate and to find that familiarity where in the site something goes, what kind of content it is. I recognized when I saw it, that there's a diataxis framework with the different content types, which is super popular in the tech space, and I feel like I've been doing it but didn't know it had a cool name. In fact, it didn't have the cool name until later. But anyway, it's a very cool name. The content types, so being able to say to a contributor, this is an explanation piece, this is a reference guide. This one is a task, it has steps, you make no choices, and you begin at the beginning and you go on until you get to the end. These are the content types, here are some templates. That really brings in contributors, but I think for technical writers to be able to do that facilitation role, we expect it from them. Like you say, those teams are always understaffed, they're already working miracles. They may not get a warm welcome, but my advice is to just keep trying.
Kate Mueller: [00:35:11] Let me see if I can summarize this back to you, to be sure I'm hitting on key points here. Part of that being, having a process that is clear and succinct so that developers can figure out where in the process they're fitting in to that. Providing a fairly simple, straightforward, whether that's checklists, whether it's templates, something so that they can just run through a list. Here's what I've done, and then be out at that point. I've given you what I need to give you in the format you're expecting it, and then you can do whatever you need to do with that. So that there is a clearly scoped request, partially. This is what I'm asking, here's what I need you to do. Plug yourself into this, do it, and then you're done. You get to say you completed this thing and you can go back to where you're more comfortable.
Lorna Mitchell: [00:36:06] Yeah, I think that's a great summary. This is so important because some of the reluctance of engineers in writing words, is that they don't feel confident. I have mostly worked with teams where the docs are standardized on English, but the engineers are not necessarily native English speakers. I mean, they all speak English, they're working in English speaking companies, but they don't necessarily feel equipped to do their thing. So letting them know, yeah I get it. Here's the template, you do your thing. Under no circumstances am I publishing that. You put it in the pull request queue and we work our magic.
Kate Mueller: [00:36:48] You remove some of that anxiety of being like, I'm not an expert in this, I don't feel qualified to do this. You say, what I'm asking you for, you are qualified for because it's the knowledge in your head that I'm really asking you for. Don't worry about making it pretty, that's what I'm qualified for.
Lorna Mitchell: [00:37:05] They are so good at the other things that they do, doing a thing that you're bad at is hard and sometimes unfamiliar to them.
Kate Mueller: [00:37:13] As somebody who is terrible at writing code, I can feel that, but in the complete polar opposite way which is, please don't ask me to do this from scratch. Let me go find a StackOverflow answer that has 80% of what I need, where I don't fully have to understand what's happening. Then I can just play around until I think I got the thing that I needed. It works both ways. Well Lorna, this has been an absolutely fantastic conversation. I want to head into what I would consider the closing portion of the episode, where I'm just going to ask you some sort of vague general stuff here. First question, are there any resources for anything that we've talked about today that you would love to share with the folks who are listening? That could be in the more technical side, it could be on the writing side, it could just be like, here's a thing that talked about glue work that I super loved. Is there anything you'd want to share? We will put links in the show notes everyone, so don't feel you have to scribble anything down.
Lorna Mitchell: [00:38:14] Okay, let's think about this. Glue work, let's share Tanya Riley's article about this. I will find it. For the resources that I've mentioned, I published a super short style guide that I use with developers, that's in a GitHub repo. You might find it useful for, ten things that you can't lint for but people should probably think about when they're writing. I've used that with technical teams, and it is a style guide that I believe engineers have been known to read. That could be valuable, we'll share the link to that. Diataxis, with the content types, let's absolutely share the link to that for anyone who hasn't seen it, or even if you have, I feel like I get something new from it every time I revisit the site or teach it to a new team. It's so valuable. The only other thing I think I would share is, the 'Write the Docs' site has a bunch of really good content and a great backlog of talks and that kind of thing. I love their docs as code resources. I think for writers who are coming closer to engineers who might be listening to this podcast, there's some really good resources there. It's been a controversial topic in the 'Write The Docs' community. This year the doc's code practice could be more approachable, and I think it's a difficult thing because one size doesn't fit all. If we could make it easy, then we would, and we can't. There's a lot of moving parts, but each moving part could be made easier. I think there's more content being shared in the space about that, and I am trying to put more of the things that I forgot that I ever learned onto my own blog as well. I'm an engineer and it doesn't always click with me, what might seem weird to someone who didn't have that background, but the 'Write the Docs' docs code page is a really good place to start.
Kate Mueller: [00:40:06] What is one great piece of advice you've been given in your life? It does not have to have anything to do with writing or tech, I just want to sponge off your awesomeness.
Lorna Mitchell: [00:40:16] A wise woman told me once, that nothing can happen until I show up. I might not know how to do a thing, or what to do about a problem, or what the next step is, but I can show up. I can always show up, and if you don't show up, nothing's happening.
Kate Mueller: [00:40:36] Absolutely true. I love that, nothing can happen unless you show up. Fantastic. Okay, last question. For folks who have now said lornajane.net, I really want to go back to 2006 and see how bad your blog posts were back then, or learn about you or connect with you in any other way. What are the best ways for them to do that?
Lorna Mitchell: [00:41:00] Read from any year, but 2012 was a particularly good vintage, I'd like to say. Visit lornajane.net. I maintain a list of all the other things that I'm doing. For example, this podcast, or any, I don't speak in public a lot now at all, but if I do, then it's on there. There are some podcasts I know in the works as well. All my social links are there in the footer as well. Look, right now I'm in a funny place. I'm between jobs, we could say. I don't know what's next, so people should reach out to me to chat or, if you need a glue person who is alarmingly technical, particularly if you have problems that are shaped like open source or APIs, they should probably give me a chat. Those are my most happy topics. Of course, now I have some time on my hands, I'll be writing a bit more on my blog. So follow along and keep up with it. I am old school, I own my domain, I have an RSS feed, and you can follow along.
Kate Mueller: [00:42:03] I love it. You heard it here, ladies and gentlemen. If you want someone who's alarmingly technical to connect with, Lorna is definitely worth checking out. I can absolutely, without a doubt certify that she is not boring to talk to. So thank you so much, Lorna. It's been a delight.
Lorna Mitchell: [00:42:22] It was my pleasure. Thank you so much.
Kate Mueller: [00:42:27] The Not-Boring Tech Writer is produced by the lovely humans at Astronomic Audio. With editing by Dylan, transcription by Alan, and post-production by Been and Alex. Our theme song is by Brightside Studio. Our artwork is by Bill Netherlands. If you have feedback or ideas for a topic or guest idea, shoot us an email at tnbtw@knowledgeowl.com or message KnowledgeOwl on LinkedIn. If you want to work with me on knowledge management coaching, go to knowledgewithsass.com. Until next time, I'm Kate Mueller, and you are the not-boring tech writer.
Lorna Mitchell: [00:00:54] Hi Kate! That is a great intro, thank you so much for having me.
Kate Mueller: [00:00:57] You're welcome. I'm sure you never thought you'd be starting off thinking, wow, what a compliment to be called 'not boring'. But here we are, welcome to the pod. For our listeners, I came from the writing world and accidentally ended up in tech and have ended up writing a fair amount of software and product documentation and a variety of other things. But for me, that was always like an accident. I just sort of ended up here and it's worked. My sense is that you've had the opposite experience, where you started more on the tech side and have accidentally ended up writing some documentation sometimes. Is that true?
Lorna Mitchell: [00:01:35] I think that's a really good reflection. I've always liked words, but I have worked my entire career in software engineering of one kind or another. Along the way, it always seems to be, I've been in charge of multiple docs platforms, and there's a thousand posts on my blog, I wrote some books. This technology thing is amazing, it's easy when you know how and I just can't stop telling people how.
Kate Mueller: [00:02:00] It's a good problem to have. One of the things I've learned is, if you are really excited about the thing you're talking about, people will show up and listen to you. I don't understand how this happens. I've done these half hour sessions at KnowledgeOwl, walking people through new features or whatever. People will be like, I love listening to you talk. I'm like, why? Why do you love this? I mean, it's great, I'm happy you showed up. Here I thought I was just talking into the void, and here we are. Can you talk a little bit about your technical background then since it's, I'd imagine, a little different from a lot of our user's?
Lorna Mitchell: [00:02:43] Yeah, definitely. Actually, confession time, my degree is in electronic engineering, so I'm actually not at all qualified to do what I do. But along the way, we did a bit of software. This is back in the day, obviously I have been doing this for a long time. Maybe you can't tell on a podcast. Anyway, I have been doing this quite a long time. My first job was in software. I wrote games initially, which was a lot less fun than it sounds. It's not the most humane end of the industry, and I have worked in a bunch of other different technical disciplines. I've mostly been in open source, mostly as a back end developer. I also have some accessibility needs. I acquired an arm injury, it's just a horrible tendonitis, in a workplace quite a long time ago. Although my background is in PHP and web development, I became an API specialist because I can't work the front end dev tools. Those all require a mouse and I am keyboard only and I have been for a really large number of years. I'm API and data specialist kind of by necessity, but also this stuff is amazing. I've worked a lot on making computers talk to each other. The humans should not have to take the information and put it in again somewhere else. This exists in the world in digital format, make it happen. In the time that I've been doing this, we've gone from overnight batch jobs to real time streaming data integrations. I have worked on all of that and everything in between.
Kate Mueller: [00:04:22] Wow, that is quite the career and personal life arc. This makes me feel so much more normal because mine has also been equally, how did I get there from here? Actually, it made total sense at the time, but here we are.
Lorna Mitchell: [00:04:38] If I'd ever had a life plan, none of this would have happened. From each place, you just have to take one more step forward. The overall map looks a little bit winding, but I think everything is part of the picture.
Kate Mueller: [00:04:52] Nothing like ending up being an accidental accessibility advocate along the way as well. Plans you didn't expect. As somebody who developed a chronic illness four years ago, totally feel you on that one. Being like, that's a curveball I didn't expect to have to accommodate into my workplace, but here I am. I personally am super uncomfortable calling myself a tech writer or a technical writer. I've never really jived with that role or title. Really, I wish that this podcast was called the 'Not Boring ___ Writer' so people could fill in the blank on how they describe the kind of writing they do, or how they view the documentation that they're doing. What role or title or descriptor would you use to describe the kind of writing that you have ended up doing?
Lorna Mitchell: [00:05:39] I've held a bunch of titles in my documenting life. Most recently I've been VP of Developer Experience. People can't have an experience if they can't use your tooling.
Kate Mueller: [00:05:55] You hear this, internet? People can't have an experience if they can't use your tooling.
Lorna Mitchell: [00:06:00] Build it, but if you're not going to build the docs, you don't actually need to build it. Because if no one can use it, it's irrelevant. So to make your stuff relevant, you need to write things down. A lot of dev-ex roles also are internal to companies. Mine was more external working for a dev tools company, but a lot of them are internal. If you're managing technical change, implementing tools at scale, all of that needs that kind of writing. Do the right thing, write it down. The less you have to write for people to get there, the better. I see it as a very multiplying, enabling thing. I think if I was perhaps born a generation earlier, I'd have been a teacher. I'm like a multiplier, I like to get things down. How did it begin? I've always had a technical blog. I have been doing this career long enough that your computer was not connected to the internet, and I would lose my useful scripts directory every single time I change jobs, and I started putting it on a public blog so that I could use it, other people could use it. The first posts on lornajane.net are from 2006, so I have been telling people things for a really long time. I've also written a lot as, technically, a head of developer relations, as a developer advocate. I've owned docs, platforms and all of those job titles, but honestly, software engineer. I have written a lot of docs, and there's an illusion that developers don't write docs. Maybe that's something that other people do, but actually senior engineers write a lot.
Kate Mueller: [00:07:39] Particularly senior engineers who don't want to have to be the person that gets woken up every time somebody has a question about a simple thing. That if they documented, they wouldn't be the person that you go to for that. In that broad scope of types of documentation that you've worked on, are there any principles for docs that have helped you in that? You've been doing this a long time, you've come to a place where you're like, yes, I recognize that these are the things I care about when I'm working on docs. Or, since you do come from the software engineer world, from the docs that you have to engage with when you're using a tool or a platform or whatever, what do you appreciate?
Lorna Mitchell: [00:08:23] I appreciate the sense that whoever wrote this had a purpose, and that's for me as a writer as well as a reader. Who is this for? What do they need? What do they have? What are you supplying? What do they already know? Because if you start with a really detailed explanation of how to use git, but this is supposed to be for very experienced developers, the very experienced developers think they're in the wrong place, they leave. The beginner developers struggle through this first part, and they can't make it through the rest because it's not for them. It has to be, first of all, having a purpose, but also understanding your audience and having a sense of what that is. Sometimes that means not explaining how to install dependencies in this tech stack. We're assuming that you know how to use npm, next step. I find that, if that's very jarring, there's steps that are skated over and skipped. Then other steps where there's a very laborious explanation of how to create a directory. That really puts me off, and it's something that I see really common around the place, that people are not clear who it's for. It makes it hard for them then to express what they're trying to tell me.
Kate Mueller: [00:09:47] I'm in the midst of teaching a knowledge management masterclass sponsored by KnowledgeOwl right now, and my first class I started off with, who's your audience and what is their purpose? If you don't know who you're writing for, or why they're coming to your talks in the first place, then you're trying to write for everybody, or you're trying to write for this tiny little sliver of, what interests you? Neither of those is going to serve your average user in any way, shape or form. It's a good place to begin with, for sure. Maybe also from a writing perspective, is a lot of the stuff you've done, lornajane.net, that stuff you were writing on your own, sharing with the world, and apparently people are reading it from 2006, which is great. In terms of the docs that you've had to create within the professional sphere, are those things you've been writing on your own or are they more collaborative in nature? How does that work for you in practice?
Lorna Mitchell: [00:10:45] It's been a real mix, although let me say, don't read the lornajane.net posts from 2006. I got better at this in 2008. From there onwards, I would thoroughly recommend. The early ones, you begin somewhere and you don't begin to improve until you begin, so that's the blog story. A lot of stuff that I've written has been collaborative, and that's in two senses. Either each article has more than one person doing the words, or each article is part of something where other people are writing the other articles, but we are presenting it as the product documentation or the project documentation for a thing. Trying to make that so that everybody can do their thing. I have worked with a mix of actual writers and 'really' not writers, and helping everybody to get the purpose to the audience, regardless of the words, because that's, very often, the easy part and has been really interesting. I also do a fair amount that is me being me, and that is usually less for documentation and more for other outlets as a developer advocate and working in developer relations in particular. But also my most recent role because it was a tiny company and you wear many hats. Writing blog content where you can be more individual and sillier than you can in docs. Using silly examples, helping those concepts to click with people and expressing things in that way, and also writing for other platforms. Particularly when I've worked places where, I've been media trained, they've got PR agencies, but it's a very technical audience that we're talking to than writing content for other outlets. Video content and writing for TechCrunch and just different things.
Kate Mueller: [00:12:42] Is there anything you've had to write, any sort of genre of writing that you've done that you really don't want to do again in the future?
Lorna Mitchell: [00:12:52] I was not a good marketing writer, I just wasn't. It's one of those things, I've worked for myself, I'm currently between jobs, so technically I work for myself again right now. It is just not a thing that I am really great at. I don't mind, but I'm conscious that probably somebody else could be doing this, and I could be doing something else. It just sort of depends on that. Otherwise, I think I'm pretty versatile. I enjoy the same content in different formats, and that's true for a speaker. Different talk content and different talk formats like lightning talks, full day workshops, everything in between. Big stage, small stage, tiny audience, huge audience. Didn't do my research, was not expecting an audience this size. All those things. The same for the written content. The detailed blog, the announcement blog post, the docs landing page, the full tutorial and the Readme for the people who insist on arriving through GitHub when there's a perfectly good landing page you've already published. I kind of enjoy that. Different voices, different lenses on the same information.
Kate Mueller: [00:14:17] I mean, really you stretch your style muscles more than anything. It is a lot of under the hood, it's a lot of the same concepts or content, but you're packaging it differently. You're styling it differently to put it out to the world. I would say, for me as well, that's the part of it I actually really love. I think if I was just writing the same content type over and over ad nauseam, I probably would get burnt out really fast. That flexibility to be like, I'm going to write this somewhat snarky blog post, and then I'm going to go work on this pretty straightforward how-to about how to authenticate this particular thing or whatever. Then maybe this release note that's got a little bit of sense of humor, because that's how I like to do my release notes. Then this massive 'Getting Started' guide that is hardcore tutorial, I'm really trying to think about where my audience is coming from and what I need to feed them, and divide that in ways so that people can get into it. Variety is totally the spice of the writing life, I think. I think you do a lot better in the writing world if you're comfortable being like, I can pivot, I can totally write that other thing. I will say, I don't think you're alone in feeling like marketing copy is not your sweet spot, it's certainly not my sweet spot. I discovered that recently working on my own website. I find it easier to write marketing copy for others, but marketing copy for myself? Not good at that.
Lorna Mitchell: [00:15:50] I always have someone else write my bio and stuff like that. This is what we do. I think the other side of that is, as well, having done roles that sometimes did report into marketing in very technical companies, meeting people and working with people who are very good at marketing copy made me realize even more that I should absolutely not be doing this. That is a proper profession and I respect it.
Kate Mueller: [00:16:19] Also, there's something to be said for having the person who's really stoked to write a given thing. What you're going to bring to the table when you're really passionate about a thing is very different than what you bring when you're like, well, I can do this. Is there anything from your background coming up on, what I would call, a much more technical path than people like myself, who came up from the writing side and then happened into tech. Is there anything that you would suggest to other people coming from that developer or engineering background who are finding themselves having to write more, and they aren't comfortable in that space? They were like, wait, I didn't think this was part of the job. Nobody told me I'd have to write, I thought I was just writing code forever, and now I have to write actual words that humans will read? Talk a little bit about that transition and what you would suggest people do if they're faced with that.
Lorna Mitchell: [00:17:20] I think this is a really tricky one, because there's a lot of culture inside engineering spaces, which really doesn't respect documentation greatly. I think if you are a writer, then you sometimes see that play out with a lack of respect for your profession maybe coming out of the more technical departments that you work with. Not every organization, but that is definitely out there. I think we do developers a disservice when we allow them to think that documentation is unimportant, below them perhaps. Somebody else's job, not relevant to their skill set. Genuinely, I think this holds them back in their careers. Maybe you know a lot of developers that don't write docs, depending where you work and who you work with. But if you know any really good developers, you'll know that actually they are really good writers. When we let the developers hold that, that's not my job, that's not important, I'm not spending time on that, I'm not investing in, even reading the 101 on it, I'm not even going to try to find out, how would I do a better job on this? I've read two articles, now I am equipped and I'm going to use those tips in this piece. When we allow them to not even go that far, we hurt their path to being really senior, really awesome developers, being at the top of their craft, because this is part of their craft.
Lorna Mitchell: [00:19:03] If you are a developer, or if you know a developer who might listen to some advice, then taking this thing seriously for what it is, maybe you're not going to be the best writer and it doesn't come naturally to everybody, but all developers, you have to be reasonably smart to do this career in the first place. It's quite formulaic, we've already talked about, who is it for, what is the purpose. Most of the time there's a template, there are three questions you have to answer, and you know how long it should be and if you should link to something else. That stuff is there, so you don't need to become a novelist, but you do need to perform this basic service to your users and to your colleagues and to your future self. Which is where my blog began, the things I've already looked up twice. Want to just read off the page next time. So for people coming in that more technical route, just understand that this is a thing that you can do and it's in your interests to do.
Kate Mueller: [00:20:13] On that note, we're going to take a break and we will be back. Stay tuned for more with Lorna Mitchell.
Kate Mueller: [00:20:20] This episode is sponsored by KnowledgeOwl. If you're looking for an owl-in-one solution to keep your software team's docs organized, KnowledgeOwl has you covered. KnowledgeOwl offers content access control for internal and public docs, flexible customization, robust security, and friendly support. Learn more and sign up for a free 30 day trial at knowledgeowl.com.
Kate Mueller: [00:20:45] All right, we are back for even more fun and even less boringness with Lorna Mitchell. Lorna, up to this point I've been focused pretty heavily on the writing side of things. I'd like to flip the script a little bit here, because it's somewhat rare for us to get somebody who's experienced so, perfectly oppositely, mirrors mine. I'm going to sponge up as much as I can from you as a technical person, as an engineer and a developer. Coming from that side, what have your experiences been like working with formal or explicitly identified technical writers? Have you had them, first of all, and if you have, what have those experiences been like?
Lorna Mitchell: [00:21:32] I've had a mixture of very formally trained technical writers, that is their profession, that is what they do. People who sort of fell into it, but maybe it's just like they're passing through. Then people who are also contributing to the same projects or doing a similar job, but without any of that formal grounding. The first thing to say about technical writers is, you cannot generalize. I'm worried about the title of the podcast. You're calling it the not boring technical writers, are you blowing their cover? They play these boring people at work, they do a job that a lot of technical people must think is really boring, and they're all so interesting as humans. It's like, is it a secret that they are not boring at all? Are we telling people? I don't know. It's been a really mixed bag, and a lot of the time it's been a real good experience. On a very personal level, working with people who actually are technical writers has been a source of great joy to me, because here in the UK, the education system, I think this is still true, but it certainly was when I did it, allowed me to stop writing more than about 200 words at a time when I was aged 16.
Lorna Mitchell: [00:22:54] I have post 16 qualifications in math and physics and engineering and that's it. So I am not really a writer. We don't teach grammar here. I do hold a qualification in Latin, which has helped me enormously, but also a lot of the technical writers that I've worked with are not necessarily native English speakers. Some are, some are not. Either way, this is so interesting because we can all nerd out about words together and things happen. I will be editing something and I'll have to go to the channel where the tech writers live and say, here is the sentence that I started with. Here is the sentence I would like to edit it to. Now explain that to me so that I can explain it to the person who wrote this also using English as a second or third or fourth language. This just sounds better to me. I'm well read, that's how I operate, but that's not useful feedback to your writer.
Kate Mueller: [00:23:56] 'It just feels right' is not useful to help somebody learn how to improve what they're doing, right?
Lorna Mitchell: [00:24:04] Exactly. Why does it matter that this verb in the past hasn't finished happening? It doesn't matter that it was ongoing, but I don't know how to explain that. Having proper word nerds around has been a brilliant experience, just on a very personal level. Working with technical writers especially, there's a breed of old school technical writer who are very certain that there is a correct way to do a thing. They may not enjoy having other people doing anything, especially if it's not done in that correct way. That doesn't gel well with engineering, which is very much like, what's the problem? How could we solve it? Is it better than it was? Great, roll with it, and then iterate. Whereas sometimes that's a very fast and incomplete process. For technical writers who I think are more trained for publishing immutably onto printed paper, that can never be replaced. It's just such a culture clash that, there can be a lot of friction there. I've had that in working with technical writers, like certainly not, that is not how we do things.
Lorna Mitchell: [00:25:22] Looking at how to bring those wordsmiths, but a lot of the time in technical writing, we need the tech writers to be editors. They're not going to write all the words themselves, they're going to make the words be what they need to be and go where they need to go without having control over every word or being the only source of the words. That moving them into the doc's code workflows and helping them to feel confident that these things are for them and for their territory, and work for them has sometimes been a bit of a challenge. The writers that I've most enjoyed working with are people who ask questions, they genuinely want to hear the answer, and they're happy to iterate and keep learning and exchanging knowledge. Keep teaching and keep learning with their technical counterparts. That's been something that I've found very positive in the places where it's worked.
Kate Mueller: [00:26:31] I feel like a bit of what you're describing there, is that you're each recognizing that you have a domain of expertise. That you're collaborating with somebody whose domain of expertise is different from yours, and you're both learning and building a thing together, rather than one of you just telling the other one, this is how it is and how it's done. Is that a fair summary?
Lorna Mitchell: [00:26:56] I think that's a great summary. I think a lot of tech writers are expected to work in that way, where they ask the expert or the engineer to tell them a thing, the engineer tells them a thing, they then write the thing down and that's the only truth that can ever exist. I think that with a bit more crossover between those roles, we can do a lot more together and we can go faster.
Kate Mueller: [00:27:18] I would say in my own experience, most of my technical stuff is, I've worked for small software companies. Usually I've been brought in, I'm wearing 4, 5, 6 different hats, writer is one of them. I'm working with a very small team of developers or engineers who are also trying to do a lot with a small amount of time and resources. For me, approaching that as, all of us have limited time and resources. We're just trying to do the best we can, both by the product from a software development perspective, but also the product by a documentation perspective. How do we do this in a way that hits 80% of a user's needs out of the gate? We feel confident in that and knowing that we can iterate on that moving forward and being less concerned with, I'm not asking those devs to write a final polished thing. What I'm asking them for is, give me a bullet point list of what you think is important. Give me the list of stuff I need to know that you don't want me to put in the docs, but you want me to understand the underlying bits so I can figure out how to structure some explanation that's going to make sense for our audience. Or, take a stab at writing it, but don't actually worry about the style guidelines or linting or anything like that. Just give me what you have and then I will polish it up. Then I will send it back to you to make sure that I didn't misinterpret anything as I was polishing it up. Now I've suddenly changed the meaning on something you put in here, and I don't want to be misadvising people. I think there is a definite give and take there. If both sides can recognize that there should be a give and take there, and that it should be a collaborative effort.
Lorna Mitchell: [00:29:09] Yeah, definitely. I do think developers should write documentation, and writers must aid and abet. We're here to be coconspirators, we're here to make it happen. I say developers should write docs, they definitely should not publish unsupervised, but they definitely can put some information into the process. That's what we need them to do, it's what the users need them to do.
Kate Mueller: [00:29:34] By the same token, I've done manual software testing for a long time, and I've always been like, please don't let me release anything ever. Also, you don't want me testing in prod because I'm good at breaking things. You don't want me being the person pushing code, you don't because bad things will happen. I should not be the one doing releases. I should not be the one signing off on that piece. I should just be signing off on the functionality that I've broken. In the same way that I think a lot of devs probably shouldn't be the one publishing something, but they absolutely should be the one helping make sure that you have created the content that needs to exist for the thing that they built. Let's not even talk about external documentation. Internal documentation, documenting stuff for yourself or for your fellow engineers or developers so that they have an understanding of how that thing works when you no longer work here, or when you're on vacation, or you're on parental leave. Nobody's going to want to bother you when you're getting two hours of sleep at a shot because you have a newborn.
Lorna Mitchell: [00:30:41] Or you just straight up don't remember this thing anymore.
Kate Mueller: [00:30:45] Because you haven't had to touch it for two years.
Lorna Mitchell: [00:30:47] Past you needs you to have written this down, already, last time.
Kate Mueller: [00:30:52] I often joke with my team that the reason I'm so good at documenting things is because I have a terrible memory. They think that it comes from this deeply principled place of 'I think things should be documented', but really it comes from a deeply principled place of knowing that I will forget a thing if I haven't had to use it for three weeks. That's why I write docs.
Lorna Mitchell: [00:31:16] Yes, exactly this.
Kate Mueller: [00:31:18] If I can extrapolate from that a little bit, if you were giving advice to writers who were stepping in to work with technical subject matter experts. Other than treating that as a collaborative effort where you both have room to learn, is there any other advice you would offer to writers in that position?
Lorna Mitchell: [00:31:40] I think one thing that we expect writers to be able to do, but I don't know how we expect them to be able to do it, is to build community, to build that collaboration piece between all the different contributors. This is super daunting, whether you feel that the engineers perhaps outrank you in a company. In many places it will feel like that. Herding those people to be part of a process that they might not be enthusiastic about, I believe that most developers can read, but sometimes it's hard to be sure about that. I try not to accuse them of illiteracy to their faces, but sometimes I wonder. I think for a tech writer to operate that process of getting people to contribute and to be part of it is super hard. For that, you need a really well defined process. Developers are problem solvers, they're very efficient. If they understand this is the goal, this is the best way to get there, they will typically do it. I like to have things like, I have two versions of a style guide in a few places. One for the writers and the more like serious people. Essentially, I've done a ten point list in a couple of places where I've got developers who are not going to read a whole style guide, and that's enough. They understand code syntax linting, so I just throw in some validators with some rules, and if it fails, they just fix it. Run the command to fix it and we're all happy. I've used markdown, lint, veil and tools like that. Super short style guide.
Lorna Mitchell: [00:33:28] Also, if I have a lot of other contributors, which I think is increasingly common in the sort of SaaS type setups, then I try to, and you'll see this if you look back at the different docs projects that I've owned over the years, I think it's really obvious, but really I've moved around jobs, you can still see those footprints in all the different places, but I often structure the doc site in a very transparent, which bits are where. That's for readers as well as writers to be able to navigate and to find that familiarity where in the site something goes, what kind of content it is. I recognized when I saw it, that there's a diataxis framework with the different content types, which is super popular in the tech space, and I feel like I've been doing it but didn't know it had a cool name. In fact, it didn't have the cool name until later. But anyway, it's a very cool name. The content types, so being able to say to a contributor, this is an explanation piece, this is a reference guide. This one is a task, it has steps, you make no choices, and you begin at the beginning and you go on until you get to the end. These are the content types, here are some templates. That really brings in contributors, but I think for technical writers to be able to do that facilitation role, we expect it from them. Like you say, those teams are always understaffed, they're already working miracles. They may not get a warm welcome, but my advice is to just keep trying.
Kate Mueller: [00:35:11] Let me see if I can summarize this back to you, to be sure I'm hitting on key points here. Part of that being, having a process that is clear and succinct so that developers can figure out where in the process they're fitting in to that. Providing a fairly simple, straightforward, whether that's checklists, whether it's templates, something so that they can just run through a list. Here's what I've done, and then be out at that point. I've given you what I need to give you in the format you're expecting it, and then you can do whatever you need to do with that. So that there is a clearly scoped request, partially. This is what I'm asking, here's what I need you to do. Plug yourself into this, do it, and then you're done. You get to say you completed this thing and you can go back to where you're more comfortable.
Lorna Mitchell: [00:36:06] Yeah, I think that's a great summary. This is so important because some of the reluctance of engineers in writing words, is that they don't feel confident. I have mostly worked with teams where the docs are standardized on English, but the engineers are not necessarily native English speakers. I mean, they all speak English, they're working in English speaking companies, but they don't necessarily feel equipped to do their thing. So letting them know, yeah I get it. Here's the template, you do your thing. Under no circumstances am I publishing that. You put it in the pull request queue and we work our magic.
Kate Mueller: [00:36:48] You remove some of that anxiety of being like, I'm not an expert in this, I don't feel qualified to do this. You say, what I'm asking you for, you are qualified for because it's the knowledge in your head that I'm really asking you for. Don't worry about making it pretty, that's what I'm qualified for.
Lorna Mitchell: [00:37:05] They are so good at the other things that they do, doing a thing that you're bad at is hard and sometimes unfamiliar to them.
Kate Mueller: [00:37:13] As somebody who is terrible at writing code, I can feel that, but in the complete polar opposite way which is, please don't ask me to do this from scratch. Let me go find a StackOverflow answer that has 80% of what I need, where I don't fully have to understand what's happening. Then I can just play around until I think I got the thing that I needed. It works both ways. Well Lorna, this has been an absolutely fantastic conversation. I want to head into what I would consider the closing portion of the episode, where I'm just going to ask you some sort of vague general stuff here. First question, are there any resources for anything that we've talked about today that you would love to share with the folks who are listening? That could be in the more technical side, it could be on the writing side, it could just be like, here's a thing that talked about glue work that I super loved. Is there anything you'd want to share? We will put links in the show notes everyone, so don't feel you have to scribble anything down.
Lorna Mitchell: [00:38:14] Okay, let's think about this. Glue work, let's share Tanya Riley's article about this. I will find it. For the resources that I've mentioned, I published a super short style guide that I use with developers, that's in a GitHub repo. You might find it useful for, ten things that you can't lint for but people should probably think about when they're writing. I've used that with technical teams, and it is a style guide that I believe engineers have been known to read. That could be valuable, we'll share the link to that. Diataxis, with the content types, let's absolutely share the link to that for anyone who hasn't seen it, or even if you have, I feel like I get something new from it every time I revisit the site or teach it to a new team. It's so valuable. The only other thing I think I would share is, the 'Write the Docs' site has a bunch of really good content and a great backlog of talks and that kind of thing. I love their docs as code resources. I think for writers who are coming closer to engineers who might be listening to this podcast, there's some really good resources there. It's been a controversial topic in the 'Write The Docs' community. This year the doc's code practice could be more approachable, and I think it's a difficult thing because one size doesn't fit all. If we could make it easy, then we would, and we can't. There's a lot of moving parts, but each moving part could be made easier. I think there's more content being shared in the space about that, and I am trying to put more of the things that I forgot that I ever learned onto my own blog as well. I'm an engineer and it doesn't always click with me, what might seem weird to someone who didn't have that background, but the 'Write the Docs' docs code page is a really good place to start.
Kate Mueller: [00:40:06] What is one great piece of advice you've been given in your life? It does not have to have anything to do with writing or tech, I just want to sponge off your awesomeness.
Lorna Mitchell: [00:40:16] A wise woman told me once, that nothing can happen until I show up. I might not know how to do a thing, or what to do about a problem, or what the next step is, but I can show up. I can always show up, and if you don't show up, nothing's happening.
Kate Mueller: [00:40:36] Absolutely true. I love that, nothing can happen unless you show up. Fantastic. Okay, last question. For folks who have now said lornajane.net, I really want to go back to 2006 and see how bad your blog posts were back then, or learn about you or connect with you in any other way. What are the best ways for them to do that?
Lorna Mitchell: [00:41:00] Read from any year, but 2012 was a particularly good vintage, I'd like to say. Visit lornajane.net. I maintain a list of all the other things that I'm doing. For example, this podcast, or any, I don't speak in public a lot now at all, but if I do, then it's on there. There are some podcasts I know in the works as well. All my social links are there in the footer as well. Look, right now I'm in a funny place. I'm between jobs, we could say. I don't know what's next, so people should reach out to me to chat or, if you need a glue person who is alarmingly technical, particularly if you have problems that are shaped like open source or APIs, they should probably give me a chat. Those are my most happy topics. Of course, now I have some time on my hands, I'll be writing a bit more on my blog. So follow along and keep up with it. I am old school, I own my domain, I have an RSS feed, and you can follow along.
Kate Mueller: [00:42:03] I love it. You heard it here, ladies and gentlemen. If you want someone who's alarmingly technical to connect with, Lorna is definitely worth checking out. I can absolutely, without a doubt certify that she is not boring to talk to. So thank you so much, Lorna. It's been a delight.
Lorna Mitchell: [00:42:22] It was my pleasure. Thank you so much.
Kate Mueller: [00:42:27] The Not-Boring Tech Writer is produced by the lovely humans at Astronomic Audio. With editing by Dylan, transcription by Alan, and post-production by Been and Alex. Our theme song is by Brightside Studio. Our artwork is by Bill Netherlands. If you have feedback or ideas for a topic or guest idea, shoot us an email at tnbtw@knowledgeowl.com or message KnowledgeOwl on LinkedIn. If you want to work with me on knowledge management coaching, go to knowledgewithsass.com. Until next time, I'm Kate Mueller, and you are the not-boring tech writer.
