Documenting the Alternative Cloud: a Conversation with Linode

Linode (a portmanteau of “Linux” and “node”) is a public cloud provider that positions itself as an alternative to public cloud hyperscalers, namely AWS, Google Cloud, and Microsoft Azure. While Linode and other alternative cloud providers (e.g., Digital Ocean, Vultr) often differentiate themselves from hyperscalers on points of price, customer service, and ease of use, they also strive for a superior developer experience, part of which means going above and beyond when it comes to documentation.

To get some insight into how alternative cloud providers like Linode create and maintain their technical documentation, I recently chatted with Andy Stevens, Technical Content Manager at Linode. Topics we covered: the specific tools Linode uses for its docs-as-code approach to documentation, how to avoid docs sprawl, and tips for creating a better documentation experience.

One thing that struck me about the conversation (amidst all the details about processes and tools) was how often Andy returned to the importance of audience: understanding that developers (and other end users) are also people, meeting them where they are, and giving them the information and on ramps they need to succeed at whatever project they are building–even if it is just creating a place to share pictures with their families.

Andy posits approaches to this question of audience–specifically, how much does your documentation expect its users to already know about your tech?–as a differentiator in the way that alternative cloud providers craft their documentation:

I think that there’s an assumption amongst a lot of people that you kind of graduate to AWS or GCP, once you’ve reached kind of critical mass. 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

While Linode also makes sure to create pathways for users who are starting from more intermediate or advanced levels of technical or product knowledge, I really like how Andy frames the emphasis on cloud newcomers as a matter of education:

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.

Indeed, tech writing is often about translation: packaging specialized knowledge in ways that non-specialists can comprehend and utilize it, or making things make sense for people who do not already know how they work.

It is also worth noting that when I asked Andy what advice he would give to organizations that are trying to improve their documentation, he again centers the reader/user/developer in his answer (with an emphasis on providing examples):

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.

And while audience and examples can get you pretty far in producing great documentation, I also like how Andy sums up his second piece of advice:

The other thing is you want it to be technically proficient, but you also want to have that level of humanity in it.

That is a great approach to technical documentation. To my mind, it is also a pretty accurate representation of one of the value props of alternative cloud per se: technical proficiency + a level of humanity (not to say that humanity is absent for other cloud providers, but in this case it is clearly a priority).

One more reason why you should read/watch the whole conversation: Andy–who has a background in poetry–answers my completely non-techie question of “Do you have a favorite poem or poet?” by tying his favorite poem to very tech-industry concerns, like imposter syndrome and the need to constantly be moving forward.

You can access the full video, transcript, and related resources for my conversation with Andy at https://redmonk.com/videos/documenting-the-alternative-cloud/.

Disclosure: Linode, AWS, Google Cloud, and Microsoft Azure are RedMonk clients; however, this post and the cited video are independent pieces of work and were not commissioned by any entity. Some of the excerpts above have been lightly edited for syntactical clarity.