A RedMonk Conversation: Documenting the Alternative Cloud

Get more video from Redmonk, Subscribe!

Summary

KellyAnn Fitzpatrick of RedMonk and Andy Stevens (Technical Content Manager, Linode) discuss the importance of documentation to cloud providers (especially alternative cloud providers like Linode). Also covered: the tools Linode uses for its docs-as-code approach to documentation; how to avoid docs sprawl; and tips for creating a better documentation experience.

Transcript

KellyAnn Fitzpatrick: Hello, welcome. This is Kelly Fitzpatrick from RedMonk. We’re here today to talk about documentation. As you may or may not know, documentation is something that is extremely important to the developer experience, or at least that’s how we see it at RedMonk. I myself come from a background in technical technical documentation and technical writing. So for me, it’s definitely something near and dear to my heart. Rather than talk about documentation and technical communication in the abstract, today we’re going to be talking about documenting the alternative cloud, specifically documentation at Linode. Linode is an alternative cloud provider, and we can probably talk for an hour about what an alternative cloud provider is, but think of it as here is an alternative to you–as someone who is a builder–to the kind of big hyperscale public cloud providers. So with me today to talk about this is Andy Stevens of Linode. Andy, can you tell us a little bit about yourself and your pathway to working on documentation at Linode?

Andy Stevens: Sure. So I am the technical content manager at Linode. I’ve been at Linode for about three years now. My path kind of starts as I think a lot of people my age started with. I was very technically minded when I was growing up, had a computer, had the internet early on, and kind of taught myself the ways of the web, building websites and things like that. But when I chose to go away to college, I wanted to do something that I felt I couldn’t teach myself and that ended up being writing. I stuck with writing, after switching majors a couple of times, I ended up getting my master’s of fine arts in poetry and initially had thought that I would go back into academia, but I hadn’t published much. And that’s kind of a barrier to entry. And Linode had this opportunity where I could write really cool Linux guides and tutorials, and I thought this is like the best of both worlds. I get to do computer stuff, I get to write and so it stuck. And so I’ve been here ever since.

Kelly: Your story is very familiar to me. I actually moved from academia specifically back into tech. And publishing there and publishing here is very different. Whatever for whatever reason. So tell us a little bit about the role of documentation at Linode and how important is good documentation to an alternative cloud provider especially?

Andy: That’s a great question. Documentation to all cloud providers is very important. One of the key things that you have to think about when you’re thinking about cloud providers, cloud services is it’s almost a commodity, just like electricity. But whereas to take advantage of electricity, you just need to learn how to plug a cord into a wall socket, the cloud can be complex and there’s a lot of knowledge that goes into understanding the best way to use and fully utilize cloud resources. I guess I’ll call them. So something that the alternative cloud and the more hyperscaler level of clouds get right is the product documentation. If someone has never spun up a server before, maybe they’re coming from a shared WordPress hosting or something like that. It’s good to have documentation that shows you how to create a server, how to set up DNS records, how to use Apache or Nginx or something like that.

That’s where the similarities, I would say, between alternative cloud providers and hyperscale providers end. I think that there’s an assumption amongst a lot of people that you kind of graduate to AWS or GCP, and once you’ve reached kind of critical mass and what you’re doing. And so the documentation is there for people who already have an idea of pretty much what to do. The alternative cloud providers have seen this as a mistake that needs correcting, I guess.

If you’re coming to us as a student or a new developer or a hobbyist or something like that, you might not realize all the things the cloud can be utilized for. So you might set it up, I use an example of a restaurant. You have a static website that has contact information for the restaurant, the menus, things like that. But then the alternative cloud providers have these great libraries where you can learn how to set up a VPN for security and privacy, how to set up a game server with your friends, how to do file sharing amongst family members for all of your family photos. The possibilities are kind of endless. And there’s less of this assumption that you know what you’re doing. Now, we do have different levels of guides, obviously, where we try to level up a user as they go from the very basics to the to the kind of big brain stuff. At the end of the day, the job of documentation is to offer a frictionless kind of environment for someone to truly get their feet wet, to get started and to become more educated. And that’s, I guess, the less spoken to product of alternative cloud providers. It’s not just servers and storage and things like that. It’s also education. You want to make someone a better customer by providing this kind of free service.

Kelly: Yeah, and I love the idea of having the different starting points and the different pathways. So whether you’re kind of getting started with Linode or you already kind of have an idea of what’s going on and are looking for slightly more advanced content, it sounds like you have everything covered.

So there is this is a great blog post up on the blog about Docs-as-Code at Linode, and I’ve written about that post before. Can you just tell us a little bit about that process and maybe some of the tools that you’re using?

Andy: Sure. So the methodology we employ is docs-as-code. And what that basically means is that we treat our documentation how an engineering or developer team would treat their code. All of our documents are Markdown files and we use a static site generator called Hugo to render them. This means that we can store all of our documentation on the GitHub repository, which is open source, and anyone can contribute to. The publication process is very similar to that of how our engineering teams deploy our cloud manager software, updates to the fleet. Basically, we work all week in individual branches on GitHub and then when we’re ready to deploy, we merge all of that into develop. We do a quick once over to make sure everything looks good. Once it’s been approved, it’s merged into the main branch. That branch kicks off a web hook to our staging development server, which we review once that’s been updated. And if everything looks good, we cut a release on GitHub, which is kind of nice because you can get zip files and things like that of all the content we’re going to publish. While we’re doing the reviewing and stuff like that, on every pull request, there are GitHub Actions that we use to check spelling. We use a tool, a wonderful tool called Vale for that and we have to test that. One of our engineers wrote that check for styling and formatting and another one to check to make sure then there are no 404 errors in any of our docs. So by the time everything hits in production has been reviewed multiple times and stage multiple times and it’s been tested.

Kelly: So in terms of so we’re talking about process of getting things, getting documentation kind of out the door and published. But in terms of processes from another point of view, one thing that we see time and time again, especially from organizations that have been around a while, is docs sprawl: everything is out there and no one has any understanding of where it is and how it’s being used. How how do you at Linode avoid docs sprawl?

Andy: That’s a really good question. The answer is we do a couple of different things and we keep trying new things. One of the patterns that I think a lot of documentation teams fall into is the versioning of certain documentation, which is a great practice in and of itself. But something might be picked up by Google and, do that search result might lead to outdated documentation. So for product documentation, we’ve been moving a lot of the product documentation into a single spot on our website where it’s kind of evergreen and updated in place. So for product documentation, we avoid sprawl that way. For our guides and tutorials, which are much more rooted in the kind of Ubuntu 16.04, Ubuntu 18.04, and they have different slightly different instructions for each one, we come up with, we create new documentation for each of those kind of distro variants. But we have a tool on our website that we just implemented that allows you to select which distribution you want to use for a specific guide. And so in that way, it’s a little bit easier. Even if you land on a kind of outdated guide, you can find the most recent up-to-date ones. In the other tool we’ve kind of been using is there’s a feature in Hugo called short guides where you can embed a guide in another guide. And for the example I like to get for this, is instructions on how to use Docker. A lot of software out there is using Docker. And we don’t want to write instructions for every guide that we would then have to update. So we update our one Docker short guide, and when the site is built, that gets generated into each of the guides that include it. So it’s a little bit easier to keep them up to date and reduces the kind of toolbar mess that people get with all of their tabs open

Kelly: Is a nice alternative to just hyperlinks to the different things that you might need.

So another kind of maybe more meta question, but any advice you would give to organizations that are trying to improve their documentation, especially for developers?

Andy: Yeah, I think that if you can have a couple of rules of thumb, you can make really good documentation. One is that you can’t assume the world of your reader. A lot of times when you find documentation, it’s written from the perspective of someone who wrote the code. And so obviously everything seems to make sense. But the reality is you might find someone who came from a Stack Overflow post and they didn’t read the first four paragraphs because they’re just looking for that one answer that they need, and they get there and it doesn’t happen automatically for them. So if you can become exhaustive and just lace your documentation with examples, especially if you’re an app developer that’s on different platforms or a package developer that has different installation methods, or you have some sort of module that can be used in many different languages. Examples, examples, examples.

The other thing is you want it to be technically proficient, but you also want to have that level of humanity in it. Taking the time to use plain speech to explain a difficult topic or offer some sort of other learning method. Maybe there’s a YouTube video that does it really well. Maybe there’s a slide deck that you could link to. You want to, you want to meet the person where they are, not where you want them to be. So if you can kind of consistently have that thought in the back of your mind, like, well, who am I really writing this for? You can you can kind of, as I said, kind of meet them where they are and make for a better consumer of your product.

Kelly: That is that is great advice, and similar advice we give, we give people the time. It’s like you need to meet developers where they are. Of course not all Linode users are necessarily developers, but meet your users where they are.

So final question–talk about meeting people where they are–based on your background, do you have a favorite poem or poet?

Andy: I switch around on my poets all the time. There’s one that I come back to all the time. It’s called “Lying in a Hammock at William Duffy’s Farm in Pine Island, Minnesota.” And the poem, it’s like anybody who has aspirations or dreams or especially someone who’s in a field where you feel like you have that imposter syndrome because you’re constantly tackling new topics every day. It’s one of those poems that kind, of it’s kind of funny. The last line is something like, “I have wasted my life” or something like that. It’s a very nice, beautiful poem. And it’s just that feeling that that the fact that James Wright wrote that it’s like, yeah, there are other people out there who want to do more with their lives. They want to succeed in other ways. They want to constantly be moving forward. And it’s OK to say at the end of the day, like, yeah, I could do more. Yeah. So even though it’s kind of a funny, kind of a downer poem to me, it proves that there’s a lot of possibility left.

Kelly: Well, thank you so much for spending some time chatting with me today. This was great. We talked a lot about technical documentation. We got to talk about poetry and a little bit more about what it’s like to document the alternative cloud.