Lorna Mitchell has been coding and writing for the vast majority of her career, ultimately parlaying this mix of content creation into a developer advocate role. In the technical space, everything from blogs and readme files to support tickets and code libraries can be considered content—and all of it should be approached thoughtfully.
I really only have one big goal when I sit down to create something new, and that is to have a clear outcome. So this should inform the developer or document a particular feature, or make one thing particularly clear.
Technical content tends to have specific formatting with short paragraphs and lots of subheadings, lists, diagrams, tables, and code. The result is visually different from standard long-form content, but it’s perfect for developers, who often scan a page for keywords rather than reading it top-to-bottom.
I always say that experienced developers are experienced skip readers. So as long as you signpost the small thing they need, they’ll find it.
Lorna Mitchell
Lorna Mitchell is a developer advocate, engineer, author, and conference speaker.
Relevant links:
Stream episode 5 now, or subscribe on your favorite podcast platform below.
Episode transcript
Note: This transcript may contain some minor wording and formatting errors. Apologies in advance!
[Voiceover] Welcome to The Future of Content, a podcast exploring how we create, manage and distribute content. Brought to you by Four Kitchens: We make BIG websites. [Todd] Welcome to The Future of Content. I’m your host Todd Nienkerk. Every episode, we invite a guest to explore an aspect of content, and to make predictions about the future of that content. If you create, manage or publish content, welcome! This podcast is for you. Today we’re talking about technical content, specifically how software engineers produce and consume content. Our guest today is Lorna Mitchell, developer, advocate, engineer, author and conference speaker. Welcome to The Future of Content, Lorna. [Lorna] Hello, thanks for having me. [Todd] Thank you for being here. So how did you first get into software engineering? [Lorna] Oh, this is a great question. I was doing electronic engineering at university, and we studied some software as part of that course. I didn’t understand why no one had taught me this before because it seemed just such a logical thing. I really enjoyed it, and I’ve been doing it professional ever since I got that degree in some other kind of engineering. [Todd] So the story of somebody pursuing electrical engineering and landing in software seems to be really common. I have a lot of friends who did exactly that. And I studied computer science briefly and got fed up with it because it wasn’t practical. So what’s going on with electrical engineering? [laughter] [Lorna] I think all of the engineering disciplines give you a really good grounding for a bunch of stuff. As software developers, we’re problem solvers, right? Engineering is all about understanding the problem space and the possible solutions, and choosing one, and making it happen. So I feel like it’s a great fit for the job that I do now. I mean, I probably can’t invent you a compiler—but it’s not something that’s come up in my technical career yet, anyway. [Todd] So speaking of the kind of work that you do now, you are a developer advocate. What does that mean? [Lorna] Well, it’s got two main strands. As a developer advocate—well, I actually work for a company called Nexmo. We do communication APIs so it’s a developer product. So one part of my job is I help developers to understand what we offer and how they can use it. So I write library codes, sample applications. I give conference talks, I write blog posts, and I try and smooth that interface between the developer and the product. The other half of my job which is way less visible, I think, to the outside world is exactly facing the other way. So explaining developers’ needs to the business. Perhaps helping out with some of the support questions and looking at tools that we can build to just improve that experience, but explaining it back into the business rather than constantly broadcasting how great the product is. Also, advocating for, “These are the things that are not great that I’d love us to work on.” So it’s very two-way advocacy, and I find it really rewarding. [Todd] So those two strands are: one, you’re trying to communicate to a technical audience why the product that you’re supporting or promoting is good for them or works well for them; while also speaking to the product company itself about then the needs that those developers have for that product. [Lorna] Well, for developers it’s not really about telling them why our product is great because developers know what they need. It’s just about telling them what it does and how to do it. So if they want to implement it because they’ve identified it as the right solution for their problem. They understand their problem better than I do— Then making sure that they have the resources, the libraries, the tutorials. The overall concept that they need to be successful with this product. [Todd] And so you produce a lot of this documentation and content, right? [Lorna] Yes, I do. [Todd] So what kind of content, in your role as a developer advocate, do you produce? What media do you work with? How do you publish it? Where does it live? What does all of that look like? [Lorna] It’s a really mixed bag. I think a support ticket is content, so I’m often trying to explain things as a one-off. We do have a blog so I write on the blog, particularly if it’s just something I wish everybody could do more easily. I’m trying to get that out there so people can find it for themselves, instead of having to find me and ask me. So, I’m scaling myself with my blog posts. I also write quite a lot of the documentation, both on our developer portal and for the libraries and the sample apps that we publish. So I’m also publishing readme files [laughter] and formal portal documentation, the smaller blog posts, some of our social media content. [Todd] You also talk a lot about “docs as code,” and the docs-as-code movement. What does that mean? [Lorna] So docs-as-code is when we write content in general, documentation in particular, in the kind of tools that we would expect to apply to code, to software. So we’re probably using source control. We’re able to look at the changes that are made more easily. We might be automating some checks, some spell checks, some publication. It might happen automatically. So we’re kind of bringing the best practice from code and applying it to the docs as well. I mean, my background is very strongly as a software developer. I’ve always had a writing habit, which is why advocacy is a great career for me but I haven’t really had a traditional documentation role. So there are probably other ways to do documentation, but I’m not familiar with those. [Todd] To what extent do you think the docs-as-code movement is born from software engineers, coders, looking to create documentation workflows that fit with their everyday workflows? Versus a true best-tool-for-the-job approach, do you know what I mean? [Lorna] Yeah. And I think there’s a few different things coming together to make docs-as-code. So I’m more active in the documentarian space now. It’s communities like RightDocs, so I meet people with different backgrounds. As engineers, I think there is a real desire to automate all the things, and I quite like that, and it’s definitely one ingredient. Another one is that writers—and especially technical writers—are themselves incredibly technical. Some of them I would hire as a developer—even though they don’t believe me that I would. So seeing them try to improve their tools and be more efficient, just do the hard parts and let the computer do the easy parts, I think is another big ingredient to this movement that we’re seeing now. [Todd] And the tools that you talk about, the workflows that you talk about. These are things like version control tools, like Git, right? So when somebody is producing documentation as code, they are creating a readme file in a Git repository and people are submitting polar requests to that, to make changes to it, additions, improvements, fixes, stuff like that, right? That’s the workflow you’re talking about? [Lorna] Yeah, definitely. But you also see not just the readme file, you see whole repositories of content. So those folders are marked down and it’s your whole documentation, your whole information architecture is there within your repository, all of the markdown files and everything are there. And then those are managed in a docs-as-code way. So we make changes through core requests, we might automate some of the builds, we might deploy a preview automatically. And then when it’s merged, it’ll get published in some way. So all of that is automated. So it’s not just the kind of words that you’d normally expect to find in a repo. The repo can be just content, and then the automation on top of that. [Todd] So for our less technical listeners, I have enough knowledge of these kinds of tools to be able to speak somewhat authoritatively about how they’re used in an editing context. But for those who aren’t familiar with what version control and Git and markdown and things like that, what they mean, a quick primer. Version control when applied to content is basically like Word’s track changes. It’s just a way to monitor suggestions and accepting—or Google’s commenting and suggestion tools. And markdown is a way to style and format text using just simple characters on a keyboard and not relying on a WYSIWYG (What You See is What You Get) editor. Is that all correct from your—? [Lorna] That’s a really nice summary. Thank you. [Todd] Well, thank you so much. Great. So what you’re then working with is using coding tools to do the things that a lot of writers and editors currently do but they use Word and Google docs, but you’re using things like Git and markdown and all of that? [Lorna] Yeah. [Todd] Okay. So you mentioned— With people, when we say, “Submit a pull request in Git,” what we mean is somebody saying, “You should make this change. Please accept this change,” right? So there are other people that are collaborating on these documents, right? What role does collaboration play in the docs-as-code movement? [Lorna] I think using a tool like source control— So putting your content into Git in a text-based format is incredibly powerful in terms of— You’re working on some new content. Somebody creates a first draft, lots of people offer some feedback, maybe some specific fixes or changes, but maybe general feedback. Then we do another version. Do I need to read this whole thing? Well, no, because I can look exactly what changed. The diff is very clear to read. If somebody’s making a small change to a large document, I only need to review the change and I can see clearly what that change is and as much or as little of the context as I want to. So I think in terms of— Like, I say, I haven’t really written documentation with any other tooling, so I don’t know how you would do this another way, but I find it a really good way to work with content. [Todd] Are there some aspects of the docs-as-code approach or philosophy that you think might apply to other industries or other roles outside of software engineering? [Lorna] I think it’s already being used in lots of different ways, and I think that docs-as-code is perhaps adopting the best of other industries already. So we see— Once upon a time, you’re particularly, more like, graphical interfaces admin would be clicking a certain series of buttons, and now that’s all text-based, mostly YAML files, and they live in repositories, and we just orchestrate as many of those as we need. And I see docs-as-code as part of the same movement. And the joy of having things in text-based markup is it’s a standard. You can use your own tooling. Everybody can use a different editor. You don’t have to learn something new. Everybody can interact with and contribute to that content. So it’s not that only the technical writers can do the documentation. I can pick the brain of an engineer and that person might even come and offer their changes to the work that we’re doing. [Todd] So when you’re producing content for a technical audience, what kind of goals do you set for yourself? [Lorna] I really only have one big goal when I sit down to create something new and that is to have a clear outcome. So this should inform the developer or document a particular feature, or make one thing particularly clear. It might be API reference, or it might be: This is how the signatures feature works on this API. Just to try and keep a clear scope but also a clear outcome. Is it a tutorial? Am I teaching you something? Is it a new feature? Do I just want to give you a quick taste and inform you about, “Hey, you can do this new thing now and the detailed docs are somewhere else.” So trying to keep focus on the goal when I’m writing is the most important thing. [Todd] So setting a goal that says, “In this presentation or in this blog post, I want to teach a particular skill.” Or, “I want to eliminate the fear of using this new tool.” Or, “I want somebody to be inspired to try this new thing.” [Lorna] Yeah, exactly. And I think in the talks and in the conference content that I create, that is much more about inspiration. You can put syntax on your slide if you want to, but people can’t remember that sitting in a conference hall, right? So that’s going to go somewhere else. But they will remember that they saw me buy a number, send an SMS. And hopefully they’ll also remember that I was quite ranty that they need to check the security of their webhooks— [laughter] That’s really, really important. And, yeah, there’s a fun demo and there’s a story, and I’ve probably put some code on the screen. But the goal is, “Oh, hey. That thing wasn’t that hard, and it’s really important.” And they go away ready to do it for themselves. And maybe it’s not a problem that they have today, but when they see the problem and they understand this is the resolution, they know where to find it. [Todd] So it’s less about trying to be exhaustive and more about just getting people to take the first step towards something. [Lorna] For conference content, absolutely. Exhaustive, sometimes. I write API reference documentation too, and that is incredibly textbook accurate and thorough, and that’s a completely different beast. [Todd] What are some of the— You deal with a lot of content and a lot of different kinds of content: conference sessions and API documentation and all of this. What are some of the common problems you see in technical content or content that’s geared towards technical audiences? [Lorna] I think it’s quite difficult to keep that scope in mind and also try to keep things short and focused, even in a longer tutorial. I like to have subheadings and keep each section quite easily navigable. I always say that experienced developers are experienced skip readers. So as long as you signpost the small thing they need, they’ll find it. I might be writing a tutorial about one thing but I also include how to generate the JWTs for this or the access tokens. It might be someone is stuck reading a different piece of documentation, finds this. This is the access token piece they need and they will run with it. So just keeping things clear and simple even if it is a longer piece, well-signposted. This is true of talks as well as tutorials. Then developers will pull the piece that they want. And I think especially for a complex problem, it’s very easy to set the scene, like, “Oh, this is a really complex problem.” And there are lots of long words in the first very long paragraph. Your developer is not going to read it. [Todd] They’re looking for some specific error message or keyword or something, and they’re going to skip straight ahead to it so you need to create what you call signposts. That could be a table of contents or section headers or easily searchable text, error messages that are specifically copied and pasted into the document—all of that? [Lorna] Yeah, exactly. I call it “furniture.” There’s probably a formal word for it—and you can hear the air quotes when I say that, right? But it helps developers to find their way around and also to find their way back up if they just saw something, and there was a list, and they read a bit further. And then, “Oh, yeah. Okay. There was a list of that. Where is it?” Then breaking things up with short paragraphs, subheadings, lists, diagrams, tables, code. Like you say, formatting the error message in a way that’s visually different, just helps people to find their way around. I think inexperienced content creators sometimes don’t know what their point is, and then also don’t give it enough furniture, not enough features in the piece. [Todd] We’re going to take a quick break and after we return, we’re going to talk with Lorna about the separation of content and presentation, and the future of technical content. [Voiceover] The Future of Content is brought to you by Four Kitchens. Our team creates digital experiences that delight, scale and deliver measurable results. Whether you need an accessibility audit, a dedicated support team, or a world-class digital experience platform, the web chefs have you covered. Four Kitchens: We make BIG websites. [Todd] Welcome back to The Future of Content. Our guest today is Lorna Mitchell, developer, advocate, engineer and author. You’ve said in the past that it’s important to separate content, the message of what you’re trying to convey, from its presentation. Why is that? [Lorna] I think it’s important because you don’t always know in what way your content is going to be reused. So people might want to read it in a different format with a screen reader. Or I quite often use Pocket which gives me a lovely readability view of articles. You can’t always rely on exactly the presentation that you had in mind. For my conference talks, I actually create my content with a separate style. So it’s restructured text, which is like another markup format. It’s not markdown but—yeah. It is far superior. I love— [Todd] You said restructured text? [Lorna] Restructured text. And they have a tool called RST to PDF that then applies a style and turns that into slides. What’s brilliant about this is it’s very easy to reuse content between really different presentations with totally different styling, but because the styles are separate, then that’s fine. I can just reuse it. And because I do a lot of different— Long talks, short talks, workshops. Maybe I’ve put together a really detailed reference like a one workshop and I want to put it in a shorter talk. Similar topics, I want to reuse my material. And that separation of content and presentation can be such a gift. Or maybe you just get to the venue and realize the projector is terrible, and you will need to go black text, white background and very simple. I can recompile, it’s my party trick. I’ll just recompile my slides while I’m plugging in the projector. [laughter] [Todd] Like a live demo? [Lorna] Yeah, like a live demo, but just an official one for people who are already in the room. Yeah. But I think there’s a bunch of places where understanding that your content could be used or reused in another context is important, and that’s where the value of the separation really stands. So you can use it and then reuse it if you wish. [Todd] You mentioned how some people might consume content using a screen reader. And by that you mean an accessibility tool that reads text aloud to people who are blind or visually impaired, or for whatever reason. I believe that you have some accessibility needs yourself, is that true? [Lorna] Right. So I have horrible RSI and I’ve been a keyboard-only user for about a decade, so I don’t point at all in my day-to-day computer use. So if I can’t do it from the keyboard, I can’t do it, which is another reason— [Todd] So by point you mean a trackpad or a mouse or something like that. [Lorna] Yeah. Any of those, yeah. I mean, I have some touchscreen devices so I will sometimes use my phone for something if I need to. So I’m switching— You can’t see but I’ve got three different devices here [laughter] on my desk, and switching between devices to get things done. But, yeah, no. In computer terms, I am keyboard only. There’s no pointing device within reach. [Todd] So earlier we talked about markdown and then you just mentioned restructured text. And these are ways to use easily available keyboard symbols to format text into things like bulleted lists and italics and bold and headers and all of this. It probably doesn’t occur to most people that a WYSIWYG editor requires you to point and click on everything to format it. And if you lock somebody into a WYSIWYG editor who cannot point and click on buttons, and particularly doesn’t have a fallback option of being able to type in an asterisk for the first item in a bulleted list or something, that those WYSIWYG editors have very serious accessibility concerns. Stuff like that probably gets overlooked all the time, right? [Lorna] Yeah. I mean, it’s something that is a huge problem for me. I was freelance for a lot of years, and when you’re freelance you can choose your own tools. And now an employee again, and that’s much harder because people send me a Google doc or— I can’t interact with that. “Oh, let’s move our stuff to Medium.” Yeah. I can’t interact with that either. So it’s interesting what I can and can’t do. Generally, stuff like markdown and restructured text, it’s a standard format. We can use any editor. I’m a vim user, which is keyboard-only anyway, and I’m incredibly productive with that. But yes, there’s certainly— It’s not that I can’t write content. I’ve published books. I know how to write. But there are lots of technical writer jobs that I couldn’t do just because of the tooling. [Todd] It’s interesting to hear how the idea of content reuse, which is becoming increasingly popular in content management circles for a lot of reasons that we’ve covered here, like wanting to publish a piece of content in multiple formats, like an e-book or a white paper, a blog post or a presentation, as you do. Also, to publish it to multiple sites or apps but storing it in one place. There’s yet another reason to centralize content and create the simplest possible formatting tool, and that is accessibility. [Lorna] Right. You include everybody when you create content in a standard text-based format. [Todd] Interesting. Let’s shift a little bit to content about software engineers, about coders, about programmers. This is something that kind of amuses me personally so I won’t inject myself into this conversation. I’m curious to hear from you, how do you feel about the way that coders, programmers and engineers are portrayed in mainstream content? [Lorna] I’m not sure how much of this I come up against. I don’t watch TV or films or anything so a lot of it passes me by. And so most of what I read is coming from the industry, but the thing that I can never get past is that those—that really amazing engineer that’s saving the day, he never looks like this middle-aged engineer. I could save the day. I’m a good coder. And so I feel I’m not well represented. And I think that’s the majority of the industry who could really—the people you would really want to save the day are not well represented in general. [Todd] Is there anything you’ve seen in mainstream content, anything, blog posts, newspaper articles, whatever, that you felt was particularly good, accurate and made sense, and did represent yourself or your industry well? [Lorna] No, really. Where would that exist? [laughter] No, I find often mainstream content deliberately misunderstands IT professionals of all kinds. It’s not just coders, it’s everybody. “Oh, what do you do?” “I’m a web developer.” “Oh, could you fix my video camera?” Not really what I do, but thanks anyway. [laughter] So I think that’s a really big hazard. There are, of course, exceptions and there are some good tech generalists around so I guess that helps a little bit. There was study that came out a few years ago about whether your gender is obvious from your Github username effects whether your pull requests will get accepted or not. And I did some interesting interviews around that from people that I felt did understand some of the issues. [Todd] There’s so much we could dig into there [laughter] and I want to go there, but we have so little time together. Maybe we can regroup at some point in the future and dig into that. [Lorna] Anytime. [laughter] [Todd] Excellent. Okay. So as we start to wrap up our time together here. I have a couple of final questions. The first is, what is the most interesting content related technology that you’ve seen recently? [Lorna] Oh, that’s super tricky. I have had a blog since 2006, and I’m still blogging on that blog, and it’s WordPress, and I can’t imagine a day when it’s not going to be WordPress. So from this you can deduce that I am really about the content rather than about the technology. I think we have lost many great articles to, “Oh, my blog seems not quite ready yet.” And it’s a big trap. There are some really cool tools around and I work a lot with API reference documentation that we’ve mentioned. I’m working with Open API. That is going to change the API landscape beyond recognition, and I am sure about that, but it’s very specific to that one niche. [Todd] Can you give us—what’s the headline of why Open API is going to change the landscape? [Lorna] Open API is a specific open standard for describing everything about your API. Once you’ve got that description, you can generate documentation, generate client sites, SDK code, generate server side code. You can create tests for it. You can spin up a mock server. Pretending to be your API so you can test all your stuff against it without running up charges, or even needing to build the API yet. You can build against it and try it out. So once you’ve done that work to describe it, instead of writing a markdown document, you write JSON or YAML. And once you have it, the documentation comes for free and you get all the rest of it. It’s going to change everything. [Todd] That sounds fascinating. Okay. And to close, looking into the future, apart from API which I do want to hear more about later, where do you see the future of content management heading? [Lorna] I think we’ll do more of the docs-as-code, but I think we’re now producing content in a bunch of different ways. Our excellent podcasts being a wonderful example. And hopefully some of them come with transcriptions, but fundamentally, they’re audio, they’re a different format. We’re seeing more video streaming. The developer advocates that I’m hiring today are like Twitch streamers, rather than— I like to write a textbook. I feel like I’m from a different generation. We’ll need a way to support those more different types of content. My big hope though is that we do continue to publish the written word because everybody can read it. It’s low bandwidth. It’s searchable. Lots of different tools can consume it. I’ve still got a lot of good things to say about prose. And I hope whatever the future is, that we still take the time to write things down and to make things available in that format, too. [Todd] Thank you for that. I agree. At the same time, I am also fascinated by Twitch streaming and that— It sounds like you’ve had a similar experience. Seeing what happens, just how people interact with the Twitch stream was the first time that I felt like, “Wow. I don’t connect with this, like, this is totally different.” [laughter] And I don’t want to say I feel old. I just feel like this isn’t part of how I grew up. This is a very different way to interact with people. I think it’s interesting but it is alien to me. [Lorna] I think it’s great. So I’m already a video course author so I feel like Twitch is just— I feel like I have something to give there. I haven’t done it yet, but seeing it come into the mainstream for software development rather than just being a gaming thing, I think is incredibly interesting. And when you give a conference talk and you’re giving a live demo, and your screens are mirrored, and you’re reading off notes, and you’re taking questions from the audience, and there’s a lot of input. I feel like the Twitch streaming experience is a little bit like that. It can feel like falling but it’s a real interesting set of skills so I’m watching that space. [Todd] Maybe like a dressed-up webinar. Maybe that’s a good way to think about it. [laughter] A big live demo that is, like, everybody is hoping that somebody makes a mistake and then you get to watch them fix it, as opposed to being annoyed by it. [Lorna] Yeah. I’ve done real-time video content like this, which is very tutorial. There’s an IRC back-channel, and it’s all a little bit chaos. And I feel like, yeah, we’ve just got to pull those tools into one place and repackaged it, rebranded it. [Todd] What a world. [laughter] Well, thank you so much, Lorna. This has been very, very interesting. I really appreciate your time. And thank you to everybody listening. Until next time, enjoy your content. [Voiceover] You’ve been listening to The Future of Content. A podcast from the web chefs at Four Kitchens, hosted by Todd Nienkerk. Produced by PJ Hagerty. Theme song is PAFRATY by DJ Listo. Find us on Twitter @FoCpodcast, and get in touch by email, future@fourkitchens.com.Making the web a better place to teach, learn, and advocate starts here...
When you subscribe to our newsletter!