Technical writing the Hashicorp way

Kaitlin Carter: Awesome. Thank you, and welcome, everyone, to the technical writing, the Hash Corporate Way presentation. My main goal for this talk is to help you become a better writer in whatever role you're in. So whether you're a solutions architect, a developer advocate, an SRE, this presentation should help you communicate complex technical topics more simply or clearly. And then, of course, you can apply this to, documentation and step by step guides, but you can also apply the concepts today to blog posts, project documentation, even emails and cover letters.

So I'm an education architect at HashiCorp, and I have many years experience in the industry with creating and delivering trainings. But most importantly, I wanna note that this topic is very meaningful to me personally. I attended a technical writing workshop about six years ago, and it really changed, the course of my career. And part of the reasons was because I was honestly a really bad writer. So it's also why this is very meaningful to me because, I started probably from the very bottom being just a poor writer, and that's why I was asked to attend the workshop.

So I wanted to cover my takeaways from that keyword from that workshop that I attended and challenge you to think about what your takeaways will be today. I know this is a short presentation, so we'll have a short agenda, but I want to let you all know where we're going. So just three short sections. We're gonna talk about preparation, so how to get started writing, some best practices on how to write clearly, and then some next steps where I'll give you some guidance on things to do next because technical writing's a long journey. So preparation.

This is essentially the outline creation phase, and I would say it's just as important as thinking about your word choice, your sentence structure, your grammar, all those things that we'll cover next. A well structured outline helps you ensure that your content flows in a logical order and helps you stay on topic. So if you are a really good writer but your content is out of order, it's not going to be terribly helpful just if just as if it weren't written well at all. So preparation will also save you time when you're writing. And I'll point out here where you can reuse content from the preparation stage.

So it's nice to think about when you're writing things even at this early outline stage that that just ends up in your income content. So what does that look like at HashiCorp? We like to start with our end goal. And you can ask yourself, what is the specific task the user will accomplish? And then from there, you create the outline of which is essentially the the steps needed to accomplish that task.

And this is what's going to ensure that logical flow, that each step is in order, and will help you stay on topic. So some tips for writing a really good specific task before I give you some examples. So specific task should be short and to the point. It should include one action verb. And if it is a technical topic, it should include those main technologies, and it should also be audience oriented.

So for example, if I'm writing for a developer audience, I'll probably wanna exclude any environment setup information from that specific task. So here's an example. And this has been changed up a little bit to adhere to an instructional design pattern, which is how we tend to write our our end goals. So we'll start with by the end of this blog or tutorial and then finish that sentence. So by the end of this blog, the reader will create a new repository through the GitHub UI.

Another Hashcorp specific example could be, by the end of this tutorial, the user will deploy HCP Vault cluster through the HCP dashboard. So you can see we have our one action verb here, deploy. We've included our main technologies, HCP Vault and HCP dashboard, And then we've excluded environment information, like any cloud details or networking details. So now that you have your specific task, you can think about creating your outline. And I always like to start by saying, first things first.

And this is what ensures your logical order that each step is gonna build on the previous one. And then you test it. Did you miss a step? Can you actually rearrange steps? And then finally, ask a peer for a quick review.

Especially at this early stage where it's, you know, a main task and a brief outline, it's a lot it's a lot smaller of an ask than an entire draft. So let's look at a complete example from our previous, specific task for deploying an HCP Vault cluster. First things first, you're gonna wanna create an HCP account, and then you'll select Deploy Vault on the overview page, etcetera. What I wanna point out from here is that, you notice that each step starts with our verb. And this is very intentional, actually, now this translates really well into section headers.

And that's exactly what we do. And so this is, I mentioned earlier, where you can start reusing content. And, for a lot of our content on the Learn platform, you will see sentences written very similar to the by the end of this tutorial. So that content ends up essentially at the the introduction or in the prerequisites, and then our outline creates our section headers. And from here, you can start filling in your content.

You can add your code snippets, your command examples, and you can start writing. So let's talk about writing. So there's a lot of best practices. There's a lot of good guidance and style guides. I'm gonna just cover a few things today that I found, people tend to make the most common mistakes around, including myself when I was getting started.

And sometimes, I still make these mistakes. So we have three key principles to stay consistent with the hashCourt voice, and these are all for the sentence, sentence structure. So we always use active voice, present tense, and directive language. So my examples here for active voice are this file configures, Terraform deploys, present tense, now configure, set the variable, and directive, download the story. Let's look at this in a complete sentence.

To install Terraform, find the appropriate package for your system and download it as a ZIP archive. So you can see we're active, install Terraform, present, find the package, and directive, download it. And when you break it down like this, you can see it's a lot easier to skim as well. Let's change this up to break those best practices. You can install Terraform by finding the binary and downloading it.

You'll need the appropriate package for your system. So we've changed this to be conditional, you can, future, finding and downloading, and passive, you will need. So this these two sentences aren't really that bad. You know? But when you look at them side by side, you're gonna start to see differences here.

So our first example is 17 words versus 20. Still not that bad, but this isn't going to be one sentence. This is going to be one sentence in a much larger tutorial. So you could end up with 2,000 words instead of, like, 1,700 words when you've gotten done with this entire tutorial. And that's a lot of extra words to ask your your users or your readers to go through.

So some more guidance for communicating clearly is your word choice. You versus we. This is first on my list because I've seen this debated a lot in the industry. I see the argument for we a lot as is friendly. It's a more friendly way to to communicate.

And that may or may not be true. But generally, we is confusing. It's unclear who's doing what. And so if you're just consistent and, straightforward about you're doing this action, HashiCorp product does that action, there's no ambiguity. So we always recommend using you.

And then avoid ableist language, like run the command, see the output. This is just gonna be additional words on the page that are generally not necessary. Or you could be more specific, and that's gonna be more helpful. So what does the command do? What are you looking for in the output?

Don't use metaphors, similes, or jargon. This also just does not translate well into your non native language. So something like configuring Vault is as easy as what however that sentence ends is probably unnecessary. So it's just actual words that you don't need. Avoid things like config file instead of just saying configuration file.

And then sorry. I'm, like, really dry today. And then finally, use short words and cut unnecessary ones. So this can be a little bit more challenging, so I'm gonna go through an example on how to cut unnecessary words. So again, the most common pitfalls for this is using negative language, repeated terms, or extraneous words.

So I'm gonna read you this original sentence, and it's gonna be kinda hard for me to read and for you to listen to. But I wanna make a point. The version attribute is optional, but we recommend using it to constrain the plug in version so that so that Packer does not install a version of a plug in that does not work with your template. That was a lot, and we can reduce a lot there. So our I've highlighted our negative language, does not does not constrain, repeated terms if does not twice, plug in a version a couple times.

And then for learn, the extraneous language is gonna be optional and recommended. So extraneous words is gonna be kinda dependent on where you're publishing, and you have to be mindful of that. So on learn, our users come for recommendations, and they're not really looking for optional information, so we can just cut that. So I've, updated this to be set the plugin's version attribute to ensure that it is compatible with that packer template. So this is reduced by more than half, and it's gonna be a lot easier to skim.

Finally, all of these recommendations come from a style guide. So if you don't wanna go back and rewatch this presentation or you need more tips, more help, there are style guides that will have all of this, including stuff like capitalization best practices, accessibility concerns, and formatting for file names, code snippets, URLs, etcetera. I definitely get asked a lot, you know, when should I use bold? When should I use italic? When should I use quotes?

How should I represent a URL on the page, a style guide will cover all of that and is really helpful. So speaking of style guides, the two that I recommend using are Microsoft's and Google's. So these are both open source. They're really, really big. So just, like, warning there.

But they will have all those like, all of that information in there. It will answer all of your questions. It's so much content, it's really useful. And we if our style guide doesn't cover something, we'll fall back to one of these two for their recommendations. I've actually written Hashcorp Learn tutorial on how to write clearly.

That's gonna be very similar to this presentation. And I have all these resources so I can share them in chat or I'm not sure if slide deck gonna share it after this. But there's a tutorial you can read that I wrote. This is actually this presentation was originally a two hour workshop. So I have an an exercise repository that I'm happy to share where you can go through and practice.

And then since it was a two hour workshop, I have a full deck as well that's publicly available with a lot more examples. So you'll have more examples of of good and bad writing. Alright. We're getting close to time. I'm sorry I saved a few minutes at the end for questions, which I think we're doing at the end of all the talks.

But, my personal takeaways from that original workshop were anyone can be a good writer, even me. And then good writing takes mindfulness and practice, and I really wanna highlight that it takes practice. I'm still practicing. I'm still getting better. I didn't just finish that workshop and all of a sudden was a good writer.

You know, I've been practicing for six years. So I feel a lot more confident about my writing now than I did two years ago than the two years before that. But I still make mistakes because I'm a human. It happens. I forget a comma sometimes.

I definitely misspell things. Maintenance is my one word that I never spell correctly. It's human. It's fine. But then, you know, just start with first things first.

That was my other big, takeaway. So what will be your take takeaway from today? And that's it. Here's my email address if you wanna contact me after this with any questions.