This is a transcript. For the full video see Tag1 TeamTalk #027.2 Documentation as code: Part 2: A Linting How To - What tools are out there and how do they work?.

Michael Meyers: [00:00:00] Hello, and welcome to another edition of the Tag1 TeamTalks. Today, we're talking about documentation as code and linting prose. This is part two. We're talking about what the tools are, the tools that are out there, what their strengths and weaknesses are, you know, why you might use one tool versus another, and, get into what tests are, how you write them, what kind of tests you can write.

Please check out part one, which is a broader overview of linting and, introducing documentation into a process that's similar to a development and automation, and coming up next in part three is going to be a demo where you can see all of this in action. I'm Michael Meyers. I am the managing director at Tag1 Consulting.

I'll be your host today. And I am joined by Lynette Miles, who is the principal technical writer at Tag1. Lynette, thank you so much for joining us. This is such a cool idea and service. can you, tell me more, like what kind of linters are out there? you know, give us a broad sense of sort of the ecosystem.

Lynette Miles: [00:01:15] Okay. So, like I said in the first - part one is that, you know, like when I started, I had no idea what a linter was. Turns out, lo and behold, a lot of the doc programs today, they have, at least what we consider - I would consider a basic linter. So you're using Google docs, Microsoft Word, whatever, you know, whatever word processing program, where it does things like, “Hey, you know, maybe you missed a period. Where's your comma, this isn't capitalized.” That's a linter. It's checking those things for you and saying, Hey, you know, that's, that's probably not right. If you want to take another look at this, you know, you can add words to your dictionary. You can tell it, stop looking at this thing. So you have just even starting out with those basic word programs, you've got it.

And then there's, I don't quite want to say more formal, but, but there's tools. So there's a, the Hemingway, I think it's Hemingwayapp.com. So Hemingway editor, and that is a real basic, a web based tool you type your, your document in or your whatever. And it will review it . I think Hemingway does things like, it will say, this is how complex your, your writing is.

This is kind of your grade level, these, and it'll catch some things like this is too long, because there's readability things like a sentence over 25 words is too long, a lot of the time and it will do things like. You know, those kinds of minor things, then you get into heavier tools like Grammarly, which do those same kinds of things, but get more intense, like checking really into the structure of your sentence and how complex each sentence is.

And then you start getting into like the real, what people really call linters like there's, some of the ones I've looked at, there's Alex JS. which I liked, but was not, was not customizable and not complex enough for what I had needed in the past. What was another one? Trying to remember all the tools now.

And the other, the other big one that I ran into was I haven't personally used, but sounds awesome. one of the other writers I encountered at the Write the Docs conference last year in 2019 was Acrolinx and Acrolinx is very, is, is very customizable. And so like, we'll talk about style guides Is very customizable. So you can give it like, here's our general company style guide, but like this piece is going to be use the marketing style. And this piece is the technical style. So you can kind of define those voices because when you're writing, say, documentation and you're explaining to a person here's how you're going to accomplish this task, you use an imperative voice.

Do this, go to this page, click this link. This is, you know, download this software. Click this to run the installer. You use that kind of a voice. When you're doing like marketing, you're kind of more friendly, maybe like a little more folksy and interactive. Right. You know, Hey, so we've got this new thing and it's going to do these things for you, you know?

So that's the style is, is a little different and I'm most of the time, I mean,

Michael Meyers: [00:04:37] They're a BS detector for marketing content.

Lynette Miles: [00:04:41] So, I don't know about an Acrolinx, but in the Vale is the tool that I have used. And that's my personal favorite one. It is not as easy to do those multiple voices, but it does in fact, have a test for buzzwords.

Michael Meyers: [00:04:58] That's great. Like, I benefit so much from, you know, just the basic things that are in Google docs.

Right. I changed tense and it highlights, Oh, you forgot this. but I'm so guilty of things like run on sentences. so it, you know, I, I'm really excited about the more powerful aspects of these tools. and, and this is all. Powered by style guides and tests. Is that how it works?

Lynette Miles: [00:05:28] Yeah. So, at my previous job, we were, our documentation was based on the Microsoft Manual of Style.

So when we started, when we first started using Vale tests, there wasn't a Microsoft Manual (style defined). So we started creating one and as we got into it, somebody else actually committed it. So we were able to basically take the rules for a lot of things. Like you don't press a button, you click a button, you, when you refer to a key, you refer to it like this, you know, those kinds of things.

And we were able to like straight up codified the word Press, are you sure that's the right word? Double check that. Cause if you're pressing, pressing is not right. Clicking is right.

Michael Meyers: [00:06:18] And especially when you're writing documentation or how tos having, you know, you know, rigid, consistent language is critical, you know, from the format of, you know, functions to the language that you use.

so there are, there are existing style guys out there that you can just plug in. You can say, Hey, I want to use the Google style guide. I want to use the Microsoft guide and that sort of forms the base of what you do.

Lynette Miles: [00:06:52] Well, we originally, we started off with some, just some basic, because there's a, there's a handful of styles that they'll just like came with.

And then we added. Well, you're not only like later somebody committed the Microsoft one. so we took that and then we had our own sets based on things that we needed as you know, as a company. So like things like here's this list of product names, these product names would have to be, they're always like this.

So like at Tag1, we have the products Tag1 Quo. Well, it's always referred to by its full name. We would not use just one. We would not use just Quo. That's not right. That's not the name of the product. So I write a test to say, Hey, make sure that this is the full name, not just this word. So that way, if that flags so that it can be double checked to make sure we're not doing it wrong.

So if that way, if somebody did do it, and tried to commit it. We can say, Nope, don't do that and make sure that it's right. So we're always referring to the same, the things correctly.

Michael Meyers: [00:08:03] use the word commit. you know, they committed the Microsoft style guide. do you mean like, like literally in the sense of like, I committed it to GItHub or.

Lynette Miles: [00:08:15] Yeah. Like it's literally in a, in, in, the styles section of the Vale Github repo.

Michael Meyers: [00:08:22] So, so, I mean, tell me, we're going to do the demo and you're going to show how this works in the next segment, but I got to know like a Vale, it's like an application that you, that you run on your desktop, or is it something that you run in the cloud on a server?

Like how does this work?

Lynette Miles: [00:08:39] I'm running it locally on as a, it's a, like, I use Homebrew like brew install vale, Done. And then I went in and I set it up to like, look at Markdown because at Tag1 we're using markdown for some of the, for a lot of the content. So I would still look at a Markdown file and then I started creating, you know, I looked at, I pulled in the regular tests, the basic tests, like prose, proselint, write-good. Just a couple of others. And then I started adding a few things that I knew I wanted to watch out for, based on Tag1 products and just flat out industry jargon that we already know and use. Like Drupal. Nobody has that as a word in their dictionary, unless they're part of the Drupal community.

So when you see the word Drupal, please don't flag that as a misspelled word.

Michael Meyers: [00:09:33] You, you mentioned that there's a detector for, for buzzwords. You can create detectors for your own things. Like, you know, how you named products, what are some of the popular or, or, you know, really important, things that are out there that you use or that people should know about.

Lynette Miles: [00:09:52] the obvious ones are things like passive voice, because it's so easy to do. And it's just so pervasive. You just don't even recognize that you're doing it. And when you're writing a blog post, no big deal. When you're writing technical documentation, it's really not so good.

It occurs to me that not everybody may know what a passive voice is.

A passive voice walked into a - was walked into, by a bar. No a bar was walked into by the passive voice. That's what it was. A bar was walked into by the passive voice. Yeah.

As opposed to the passive voice walked into a bar.

Michael Meyers: [00:10:39] So it detects that you're using these things. what else? In addition to the passive voice and sort of the product stuff. The buzzwords,

Lynette Miles: [00:10:51] There's so many different things. So, one of the big ones that I ended up implementing later on, was like, I inherited a doc set and this particular doc set, it was written with he/she. So, you know, so and so such and such thing was going to happen. And then he, or she, or she could do the thing. Why not just, they.

So it would flag he or she changes this today, make it, you know, gender neutral, make it singular They. It's cleaner. It's easier to read it is, you know, stuff like they're the big one that's been going around lately, like a whitelist and blacklist. People are changing from the white list, black list to allow list and blocklist.

You could very quickly. Right. And I'm sure somebody probably is. I haven't looked, but I'm sure somebody has written one looking for this kind of thing. That's the kind of, you know, because, or, you know, the master branch or master, slave databases, those kinds of things where we want to be, you know, maybe not using that terminology anymore.

Those are the, those are those kinds of things are actually really easy and straightforward to catch and make those little changes that are more inclusive and make your documentation and your writing in general, just more approachable.

Michael Meyers: [00:12:17] That's great. And it enforces things that, you know, you often don't necessarily, actively think about, you know, I might forget to do something this makes sure that you do it.

Are these all, are these just things that are included in Vale? Do you, do you find them online and download them elsewhere? is it both?

Lynette Miles: [00:12:42] Mostly I have, the people tend to be real. The people who are using it actively, they tend to be pretty open about committing it back to the, you know, when it, when it's not like too specific to them.

So like GitLab, for instance, they're using Vale. They have it actually in their repository, you can see what their rules are. They're not committing those things back to the original repository because it's too specific to their company, but I couldn't remember how to format a spelling test. So I, but I knew there was a spelling.

They had a spelling test in there. So I went and took the format to write it for, for one of the tests that I needed to do.

Michael Meyers: [00:13:23] So these,

Lynette Miles: [00:13:24] I knew they had it done and it was right. Cause Amy did it.

Michael Meyers: [00:13:27] these tests are, are largely open source. that's, that's fantastic. Is Vale itself is, is the underlying program, is, is that open source too?

That's amazing. So the whole ship is open source.

Lynette Miles: [00:13:45] Yeah.

Michael Meyers: [00:13:46] Who created Vale. Is that, is that a Git thing or?

Lynette Miles: [00:13:50] a guy named Joseph Kato. jdkato on GitHub and he owns the repository. He wrote a really nice long post, introducing it back in. I want to say July of 2018, we first encountered it in February or March of 2019, and just adopted it and went nuts.

So it's got a pretty, it's not a huge community, but it is a fairly vibrant and active group of users.

Michael Meyers: [00:14:27] But before we jump in the demo, what is this stuff like? I want to write a test. I want to write, I want to have a style guide. you know, is this something it's sort of structured, markup thing?

Like .

Lynette Miles: [00:14:43] YAML. YAML files.

I, like I say, I was like, I don't know anything about you. I've seen like, you know, Oh, Composer. Great. I know nothing about how that works. Cool. I'm going to copy and paste stuff and then modify it. And I do. That's what I do. Cause I'm like, this is not my area of expertise. I have a guy for when I need code.

You know,

Michael Meyers: [00:15:13] and he's a fantastic world class to say the least,

Lynette Miles: [00:15:18] he comes in handy.

YAML files, structured text, with all of these great examples out there, so that you can, create your own tests based on other things. So you can get up and running really quickly with this, with some really sophisticated, and powerful checks.

Lynette Miles: [00:15:45] yeah, I mean, and that's what we did is we took those basic checks. Added them in. And then we were like, okay, now, now we need to apply our styles on top of that. And now we already had a written style guide. We had like this 30 page - Here's how you do these kinds of things. There was a lot of overlap with the Microsoft manual of style, which is this enormous.

Well, when it was still a printed book was like 400 something, I think, page style guide of here's how you refer to everything in the Microsoft separate universe. I actually more hardware and sell offer, because it talked about all their different hardware products too. So, you know, we had that. And then, so we took that and then we made our own separate style set.

And then we wrote the specific tests that we needed that applied only to us as part of that as well. And it was actually, it was really easy because we had all of those great examples.

Michael Meyers: [00:16:41] I can't wait to see this in action and that's coming up next in our next segment. Folks, if you haven't seen part one, which is just a general broad overview of what this is and how it works, check that out.

The demos coming up next, all the links that Lynette just mentioned are going to be in the show notes. So check them out. If you liked this talk, please remember to Upvote Subscribe and Share it with everyone.

You know, please check out past tag team talksat tagone.com/tagteamtalks. Send your feedback to tagteamtalks@tagone.com.

We'd love input on what you like. Don't like it, right? And topics that you want to hear us cover in the future. A huge thank you to everyone who tuned in today. And Lynette thank you so much for joining us, we'll be back.