This is a transcript. For the full video, see Tag1 TeamTalk #027.1 Documentation as code: Part 1: A Linting How To - What, Why, and How?.
Michael Meyers: [00:00:00] Hello and welcome to another edition of the Tag1 TeamTalks. Today we're going to be talking about documentation as code and linting prose. This is a three part series. This is part one. We're going to be talking about what it is, why you want to use it and how it works. In part two. We're going to talk about the tools and what's out there, the ecosystem and give you a sense of how they all work compared to each other, and part three, we're going to talk you through a demo or for the folks that are watching, show you the demo. So, I'm really thrilled. Lynette Miles is here with me today. Uh, she is the principal technical writer at Tag1. She brought up this topic and I was so excited when I heard about it.
It's super cool. I'm Michael Meyers, the managing director at Tag1, and I will be your host today. So with that, let's get started Lynette. Welcome. Really appreciate you doing a Tag Team Talk. What does documentation as code mean?
Lynette Miles: [00:01:02] In a lot of ways? It is exactly what it sounds like it is treating in your docs, maintaining them the same way that you would treat your code.
You would use version control. You do testing . You put it through all of those same kinds of quality control, peer reviews that your code does. You don't just if, and ideally let me say, ideally, because there are a lot of lone writers out there who don't have that kind of a review process, but ideally if you're working in a team or even if you've got, you still want it to have a second pair of eyes on your documentation, As well as, as much as it's important as it is with your code, because there's always that one, “Hey, you know that step's not right. That's renamed funny. Do we really do it that way? Does that make sense?” So, you know, you catch not only problems with your documentation, but sometimes you catch code problems and UI problems because you got that second and third pair of eyes looking at your code or your docs. So, I mean, if you treat them the same. And the other part of it is if you can treat your documentation, write code and it's in your repositories and you're working with it and with the same workflows and tools that your developers are using, it lowers the barrier for contribution for anybody who's used to working in the same kind of - in that kind of workflow.
I have my docs in a Github repo. Cool. If you know how to use GitHub or, you know, whatever, it's easy for you to make a PR. You already know how to do that because you've done it with your code.
Michael Meyers: [00:02:43] Fascinating. So introduction of automation and testing, essentially, as it applies to, to written content. In development, you know, automation like the CICD process, you run your code through different things, like say security checks, style checks often you use linters.
Um, this sounds like a very similar kind of thing. Uh, a linter for, for prose. Um, can you give us a, you know, what is a linter in general sense? And, and how does it, you know, is there a difference between the way it works on, on code or is it literally just the same and applied to documentation?
Lynette Miles: [00:03:23] Um, I mean, so a linter in a lot of ways is like a syntax checker.
It will catch, little, it will catch things like, Hey, maybe this isn't the way you wanted it. Or, hey, this is an error or this format is wrong. Those kinds of things. So like the first time I ran across it, I had no idea. Like, I've heard the word linter forever. I'm married to a developer. I worked with developers, I'm a technical writer.
I worked with developers all the time and I see the word and I'm like, “Oh, that's nice. But whatever it is, it's not in a context that makes any sense to me.” So whatever - I ignore it, go on. So there is a group, a group called Write The Docs. This is a group of technical writers. They put on a conference, they have a Slack, it's all technical writers and technical content creators, fantastically, awesome people.
So one day I'm sitting there. So I used to work with Amy, Amy Q? Who, if you know, Amy, Amy is fabulous and she's, she was our editor. She's like, I really need something to just look for passive voice and this kind of contraction, because it sucks up so much of my editing time. And I happened to flip over to the Write The Docs Slack that day.
And, and there's a Test The Docs channel, and one of the guys, Mike Jang, who's a writer in Portland and he's one of the Write The Docs conference organizers for Portland he's an awesome guy. He's asked if anybody used a tool besides Vale for linting for prose. And I was like, wait a minute. Linting and prose. Now I need to go look this up.
So I go and I look up until he says, and I was like, yeah, this is a syntax checker for your prose. And it will catch passive voice. And it will look for these things. I'm like, This is exactly what we need. And I turned it around and I handed it to Amy and I said, look at this thing. And 48 hours later, we had a full suite of tests just with the base style and some basics that we were writing that we needed for our particular thing.
And ijust because of that, we were able to cut off hours and hours of editing time. Because as a writer, I could be like, Oh yeah, I did that wrong. I did that wrong. I did that wrong. They fix those really quick before even anybody else even sees it.
Michael Meyers: [00:05:32] So, committing code it, you know, it can reject it if you don't meet style guides and it can give you input and feedback. Yeah, I love that. You know, like I am not a professional writer and I, I often switch back and forth, you know, between like the passive voice and I don't even catch it, you know, like when, when I like read my email and so, you know, this sounds like something that I could use, even as someone who doesn't write professionally just for my emails or proposals, you know, things that I send to clients that this this is hugely helpful for individuals that work on their own, not just writers and writers that work on their own, but phenomenal for teams.
It sounds like. Uh, and enforcing style guides. Um, you know, we were talking the other day about how a headline should be written and, you know, we were editing a blog post and yeah. And the cool thing about this is, you know, once we agree on the style w you know, our case was Lynette you tell me what to do,
Lynette Miles: [00:06:40] I love doing that.
I admit it, it is, it is fun to tell people what to do.
Michael Meyers: [00:06:44] Um, once we, you know, once we agreed upon the style for this, you know, then you, you can code that into your, your linter. And when you run your blog posts against this, my understanding then would be that it checks it against that and tells you whether or not you're meeting the style guide of the Tag1.com blog posts.
Awesome.
Lynette Miles: [00:07:06] And if you really get into it, so like interesting, fascinating timing yesterday Joe Schindler actually tweeted about what they're doing at Drupalize.me. And they have like it's awesome. I just, they have it set up in what it sounds like they've got like a, basically they have it linter so it checks all of their syntax. And then they go in, they actually have tests that will go through what they've written and actually test what they've written to make sure their instructions are right. So they'd go like full CI for their tutorials and documentation. And I'm just like, this is awesome!
Michael Meyers: [00:07:45] I can't wait for you to show this in action later because I mean, I get it conceptually, but I'm having a little hard, you know, it's like, I can't believe how.
You can automate some of these things that fascinate you, that you can check for that kind of stuff, you know, patterns I get you know the, you know, the passive voice and, and what you just mentioned, it seems so much more complex than what I thought would have been possible.
Lynette Miles: [00:08:12] Yeah. I mean, what the Drupalize/me folks are doing is like that is, I think that I really feel that there's the future of documentation, that is like where they can go and fully I'm committing this tutorial. Great. It meets all of our style guides. The instructions are correct, and it will compile and it will render. Cool. I mean, and the more that you can automate, the more time you can spend writing new content.
Michael Meyers: [00:08:41] Hmm, same benefits as automation in the development process applied to documentation. And the really exciting thing about that is it, it, it applies to so many people on your team, you know, just you know, one of the fascinating things about Drupal that makes it so powerful is things like site building, where you can take non technical people and you can involve them in, in the website, building and creation process.
Uh, this is a really powerful tool and approach that the entire team can benefit from as well as individuals that aren't on development teams, you know you know, just writers and you know, like you're talking about people, we're sending out emails. Um, so before we wrap up, um Can you give me a background, like you know, a quick insight into how this has changed, you know, your approach to writing the benefits that you've seen from this?
Lynette Miles: [00:09:41] Uh, so personally, like I know, I, I know I also have a thing about passive voice. Like it's just, it's still easy to fall into that pattern. Right. Um, there was the time where I accidentally committed something, not - I was writing a paragraph. I was writing a page and I had trouble coming up with the opening.
And that's just like the opening paragraph to introduce a page. And I'm like, “okay, so you can do this thing because why the hell not?” And I committed it. I went and I finished the page or, but all the rest of the documentation, I'm going to come back and fix this. I didn't - totally forgot it. Committed, it sent it on to the editor.
Amy comes back to me 10 minutes later with, are you messing with me? And she did not use the word messing, but she's like, what, what is, what is this? And I was like, I forgot to fix that line. Didn't I? Yeah. So something like this is like, after that I put in tests for things like maybe we shouldn't use swear words in our commits. So that you, you know, That was the only time I've ever done that, that got committed, but it only takes one time.
Right? And then, you know, it's embarrassing and you look unprofessional and your company looks unprofessional. So, you know, just catching. Goofy stuff, even if it's just goofy stuff that you put in there to try to get yourself going, you don't want that in later.
Michael Meyers: [00:11:11] You're going to have to show me how to create a test that requires a minimum number of swear words in my emails.
Lynette Miles: [00:11:18] I wonder if you can do that.
Michael Meyers: [00:11:23] We'll give it a dictionary which I'd be happy to create. Uh,
Lynette Miles: [00:11:28] there's actually a, there's actually a couple of tests, at least for the linter I'm used to using for profanity and gender and slurs. And it's great. So you can do things like catch insensitive and sensitive inappropriate language because that's, you know, that's, that's really good.
Michael Meyers: [00:11:48] Awesome. Well, that's what we're going to talk about next. Uh, which is, you know, what these tools are more specifically and how they work. Uh, so thanks everybody for joining us for part one of documentation as prose and linting code coming up next is getting into the tools and how they work. And segment three is going to be a demo where you can see it in action.
Uh, Lynette mentioned some really awesome resources. They're going to be in the show notes. So check out the posts for links to everything that we talked about, please remember to upvote and subscribe and share this to your friends. Check out past team talks at tagone.com/tagteamtalks as always, please feel free to write us.
We'd love your input and feedback. A tagteamtalks@tagone.com and a huge thank you to everyone who joined us today. And Lynette for giving us this great overview. Thank you.