[00:00.000 --> 00:13.080] My name is Portia, I'm from Document Right, we write technical documentation and today's [00:13.080 --> 00:23.880] presentation is called Automate the Pain Away, CICD Workflows for Documentation, so once [00:23.880 --> 00:30.600] again, it's me, I run a technical documentation agency, before then I used to work as a Django [00:30.600 --> 00:38.720] developer, I spent years, too much time tinkering with side projects and working with documentation [00:38.720 --> 00:46.240] and you can find me on Document Rights, on Twitter and YouTube. [00:46.240 --> 00:52.000] What we'll cover, what problem we're trying to solve, the tools that exist, how to automate [00:52.000 --> 00:59.160] your docs and the pros and cons to automation. [00:59.160 --> 01:05.400] So I talk to clients and a common problem they tell me is, sounds like a developer wrote [01:05.400 --> 01:13.480] the docs, I'm like, okay, and we dig into exactly what does that mean, sounds like a [01:13.480 --> 01:15.000] developer wrote the docs. [01:15.000 --> 01:19.760] So some of the problems that companies have with their documentation include a wall of [01:19.760 --> 01:27.240] text, which means it's really hard to parse through the documentation, it lacks context, [01:27.240 --> 01:33.360] this is really common because if you wrote the code, you really don't know what an outsider [01:33.360 --> 01:40.360] will be like confused on, it's out of date, it's not updated on a regular basis, the documentation [01:40.360 --> 01:47.520] is incomplete, there are some features that lack documentation and finally it's incohesive, [01:47.520 --> 01:53.760] it's very obvious that your Go developer, your React developer and your marketing person [01:53.760 --> 02:00.600] all worked on the documentation and you can tell which section they worked on. [02:00.600 --> 02:08.120] So quick tour of voice and tone, if you want your documentation to sound cohesive and not [02:08.120 --> 02:12.560] like four different departments touched it or sound like developers wrote it, it's really [02:12.560 --> 02:15.240] important to know these concepts. [02:15.240 --> 02:23.840] So this is a voice chart and the purpose of a voice chart is to make sure that your documentation, [02:23.840 --> 02:29.960] like I said before, sounds cohesive and this is based on different principles. [02:29.960 --> 02:36.080] So you get together with your team and you figure out what do we stand for and based [02:36.080 --> 02:43.840] on what you stand for that actually informs the concepts, vocabulary and grammar that [02:43.840 --> 02:46.080] you will use in your documentation. [02:46.080 --> 02:52.240] I can talk about this but it's easier to actually give you some real examples. [02:52.240 --> 03:00.080] So this is Google's voice, this example I'm using comes directly from Google's documentation, [03:00.080 --> 03:05.120] I promise this is not my opinion, this is just Google. [03:05.120 --> 03:09.520] So if you're looking at Google's documentation, they tell you that some of their principles [03:09.520 --> 03:17.160] include timeless documentation, catering to a global audience and accessibility, that's [03:17.160 --> 03:20.840] all nice and good, but what does that mean? [03:20.840 --> 03:26.480] For concepts with timeless documentation, it means it's avoiding words and phrases that [03:26.480 --> 03:31.440] anchor documentation in a point in time, like 2015. [03:31.440 --> 03:38.760] Vocabulary, it avoids words like now, new and currently, that's in their style guide [03:38.760 --> 03:42.160] and grammar, it uses the present tense. [03:42.160 --> 03:48.200] So you take your principles and from there, you actually figure out what concept are you [03:48.200 --> 03:52.600] going to use, which vocabulary are you going to use and not use and what is your grammar [03:52.600 --> 03:55.760] going to be like. [03:55.760 --> 03:58.640] Second example, Microsoft. [03:58.640 --> 04:04.520] This comes from Microsoft's style guide documentation, once again, I've not made this up, these are [04:04.520 --> 04:09.840] not my principles. [04:09.840 --> 04:17.080] Warm and relaxed, crisp and clear, bias free communication. [04:17.080 --> 04:23.360] So if we look at crisp and clear, it means that we're to the point, we write for scanning [04:23.360 --> 04:29.640] first, reading second, we make it simple above all, vocabulary, whenever possible, choose [04:29.640 --> 04:36.520] words that have one meaning as opposed to words with multiple meanings and grammar, make [04:36.520 --> 04:42.800] every word sentence count, concise, clear sentences. [04:42.800 --> 04:48.360] So once again, it's easier for you to get to concise, clear sentences, it's easier [04:48.360 --> 04:53.560] for you to get to whenever possible, use words that have one clear meaning when you know [04:53.560 --> 05:00.360] what your principle is, that's something that should not be avoided. [05:00.360 --> 05:03.320] We talked about voice, there's also tone. [05:03.320 --> 05:08.760] So you can have a voice, but you can have different types of tone for a voice. [05:08.760 --> 05:13.920] So if you have a warning label, you'll have like, it'll be urgent, you have an urgent [05:13.920 --> 05:17.320] tone, but the voice is the same. [05:17.320 --> 05:22.960] If it's empathy, like a getting started guide, you want that person to feel like, yes, they're [05:22.960 --> 05:29.400] welcome, yes, they should spend their whole weekend with your documentation, whole weekend. [05:29.400 --> 05:34.520] And inclusiveness, the introduction is also welcome. [05:34.520 --> 05:40.880] This is what we're about, yes, this documentation is for you and will solve your problem. [05:40.880 --> 05:42.920] Those are the different tones. [05:42.920 --> 05:50.120] And once again, you have one voice, but several different tones in your documentation. [05:50.120 --> 05:57.200] All of this is codified, not in the product manager's head, not in the lead engineer's [05:57.200 --> 06:00.680] head, but in a style guide. [06:00.680 --> 06:05.720] So the examples that we looked at were from Google and Microsoft style guides. [06:05.720 --> 06:09.600] So there's several different style guides that you can use for technical writing. [06:09.600 --> 06:13.240] There's a Google, Microsoft, Smashing Magazine has one. [06:13.240 --> 06:17.120] And the one that I personally use for my team is Digital Ocean. [06:17.120 --> 06:22.800] I love Digital Ocean's technical writing guide because it gets to the point, and it gets [06:22.800 --> 06:24.280] the information really quickly. [06:24.280 --> 06:30.000] If you're using Microsoft style guide, it's literally over a thousand pages, literally. [06:30.000 --> 06:33.960] And I think Google is around over a thousand pages as well. [06:33.960 --> 06:39.320] So even with the best intentions, one just doesn't have time for that. [06:39.320 --> 06:43.120] Here is a list of common documentation pitfalls. [06:43.120 --> 06:48.240] This data comes from the Google season of docs 2021, and some of the pitfalls that you [06:48.240 --> 06:54.720] have of documentation include the documentation is lacking, specific use cases, the documentation [06:54.720 --> 07:00.600] is disorganized, it's outdated, not consistent. [07:00.600 --> 07:01.920] You don't know of these problems, right? [07:01.920 --> 07:04.960] Your documentation's perfect. [07:04.960 --> 07:09.600] And the documentation needs to be converted into a different tool, platform, or format. [07:09.600 --> 07:11.680] Oh no! [07:11.680 --> 07:13.440] So many moving parts! [07:13.440 --> 07:17.080] No wonder why no one keeps up with their documentation. [07:17.080 --> 07:21.680] You have voice, you have tone, you have the fact that it's out today, you have the fact [07:21.680 --> 07:26.760] that people are using different tools, how do you keep it together? [07:26.760 --> 07:29.880] Automation to the rescue! [07:29.880 --> 07:35.760] So this is where we're going to use CICD tooling and automation to make sure that we take our [07:35.760 --> 07:42.240] principles and best practices and actually implement them. [07:42.240 --> 07:44.400] So we're going to take a step back. [07:44.400 --> 07:52.120] Using a CICD workflow is part of a docs as code workflow, and with a docs as code workflow, [07:52.120 --> 07:53.600] it has several parts. [07:53.600 --> 07:56.840] One, you're using version control like Git. [07:56.840 --> 08:03.800] Second, you're building documentation with an open source platform like Spinks, Gatsby, [08:03.800 --> 08:05.880] Next.js, Docsaurus. [08:05.880 --> 08:09.280] The documentation is written in MDX or Markdown. [08:09.280 --> 08:14.400] I know there's some ASCII people out there, but in this presentation we're going to talk [08:14.400 --> 08:18.160] about Markdown, and you make use of CICD tools. [08:18.160 --> 08:23.520] If you want to learn more about docs as code, you can read Anne Gentel's book, Docs Like [08:23.520 --> 08:24.520] Code. [08:24.520 --> 08:30.040] Her first edition was 2016, and she just updated it actually last month. [08:30.040 --> 08:31.040] She's amazing. [08:31.040 --> 08:32.040] I love that book. [08:32.040 --> 08:35.040] I'm going to read it to everyone. [08:35.040 --> 08:36.040] All right. [08:36.040 --> 08:40.280] Automating your team style guide starter pack. [08:40.280 --> 08:45.400] So in this situation case, we're going to use GitHub Actions, Markdown, and Veil. [08:45.400 --> 08:47.520] I'll talk about what those tools are. [08:47.520 --> 08:49.640] So GitHub Actions, the basics. [08:49.640 --> 08:52.560] It's a CICD solution provided by GitHub. [08:52.560 --> 08:54.960] It's made up of workflow and events. [08:54.960 --> 09:00.640] It contains a marketplace of third party actions, so you can write your own actions, but you [09:00.640 --> 09:04.520] can also use actions that are already pre-written in the marketplace. [09:04.520 --> 09:07.200] And it's great for running linters and tests. [09:07.200 --> 09:13.200] Many of you probably already use it for JavaScript and Python and other programming languages. [09:13.200 --> 09:14.360] Markdown. [09:14.360 --> 09:16.040] It's platform agnostic. [09:16.040 --> 09:19.640] Use it with platforms such as Gatsby, Hugo, or Docosaurus. [09:19.640 --> 09:21.000] Not as complex as code. [09:21.000 --> 09:25.600] I put this down because many people who are touching your documentation, they're not always [09:25.600 --> 09:27.520] engineers. [09:27.520 --> 09:34.720] And in our team, we have a project manager, and she did not know anything about Git. [09:34.720 --> 09:40.720] She knew nothing about code, but she actually updates documentation using Markdown. [09:40.720 --> 09:46.160] Another thing I like about Markdown is you can use MDX, and MDX is where you can import [09:46.160 --> 09:48.120] and use React components. [09:48.120 --> 09:53.200] So if you want something that is interactive, MDX really gives you some more flexibility [09:53.200 --> 09:56.240] in MD. [09:56.240 --> 09:57.240] Veil. [09:57.240 --> 09:59.440] It's not a linter for pros. [09:59.440 --> 10:08.160] There are extensions for Visual Studio Code, JetBrain, and Vim, and Emacs fans out there. [10:08.160 --> 10:11.000] It's not the only linter out there. [10:11.000 --> 10:13.000] You can check out Woke and WriteGood. [10:13.000 --> 10:19.520] The one thing I will say is with Veil, you can use many linters within Veil, and Woke [10:19.520 --> 10:22.840] is what it sounds like. [10:22.840 --> 10:26.080] I'll let you check that out on your own time. [10:26.080 --> 10:29.280] The code. [10:29.280 --> 10:32.720] So I'm going to, let's see. [10:32.720 --> 10:39.520] If we have time, I would love to run a demo, but we'll see what happens. [10:39.520 --> 10:43.960] And I would have to use a second screen, so let's just stay with this for now. [10:43.960 --> 10:48.200] This is the Veil config file, and the Veil config file, what you're looking at is the [10:48.200 --> 10:50.600] style path, the alert level. [10:50.600 --> 10:53.480] I believe there's three different alert levels. [10:53.480 --> 10:57.120] All kind of format you're using, which is markdown, and style guides. [10:57.120 --> 11:01.320] In this case, you're not writing your own style guide, but you're using style guides [11:01.320 --> 11:05.240] created by WriteGood and Google. [11:05.240 --> 11:08.840] And this is what a typical workflow looks like. [11:08.840 --> 11:15.280] This is the Veil one, and you have on, which triggers the workflow. [11:15.280 --> 11:24.120] So the trigger is, in this case, a push, and this code will run on a main branch. [11:24.120 --> 11:28.680] You're not stuck on one branch, like if you want to run this on multiple branches, you [11:28.680 --> 11:32.480] can, but in this situation, we're just using one branch. [11:32.480 --> 11:39.480] And if you go to 25 to 27, those are the style guides that we're using in this situation. [11:39.480 --> 11:45.920] We're using Google, and we're also using WriteGood. [11:45.920 --> 11:50.280] I just added this today, because I don't want this to seem like magic. [11:50.280 --> 11:56.800] When you're using Google's Veil YAML file, this is what it looks like. [11:56.800 --> 12:00.240] It's basically a regular expression, checking this. [12:00.240 --> 12:05.480] This is the first person one, and it's checking to see if you're using I. [12:05.480 --> 12:11.320] What you could do is, if you want to make your own Veil, linter, you can go to Google. [12:11.320 --> 12:18.560] You can go to Microsoft, and you can use their examples to help you get started. [12:18.560 --> 12:20.120] Finally, takeaways. [12:20.120 --> 12:23.160] The benefits of automating your documentation. [12:23.160 --> 12:28.080] It greatly speeds up the publishing process, which is a plus. [12:28.080 --> 12:31.560] The git increases workflow transparency. [12:31.560 --> 12:33.760] Git blame. [12:33.760 --> 12:39.440] It encourages developers to take a more active role in maintaining documentation, because [12:39.440 --> 12:47.720] it's using the similar tools that developers are using to develop code, which is Git, Vim, [12:47.720 --> 12:52.440] MDX, and it upskills technical writers. [12:52.440 --> 12:57.480] There are many technical writers out there that are not software developers, and they [12:57.480 --> 13:01.080] ask a developer, well, what do I need to know? [13:01.080 --> 13:02.960] What kind of coding skills do I need? [13:02.960 --> 13:06.160] And they're like C++, which is fine. [13:06.160 --> 13:07.160] It's fine. [13:07.160 --> 13:14.080] But we're not giving them the kind of advice they need to use this on a day-to-day basis. [13:14.080 --> 13:21.280] So if you go to Twitter, if you go to LinkedIn, if you go to write the docs Slack channel, [13:21.280 --> 13:30.160] there are technical writers who want to know how to upskill, and knowing how to use markdown, [13:30.160 --> 13:36.560] knowing a sprinkling of HTML, CSS, JavaScript can really give them the skills where they [13:36.560 --> 13:40.200] can actually use this on the job, which is really important. [13:40.200 --> 13:44.480] So you have these coding skills that they could actually implement, and that's one [13:44.480 --> 13:47.400] of the reasons why I like the docs as code. [13:47.400 --> 13:48.400] Caveats. [13:48.400 --> 13:52.840] These are the cons. [13:52.840 --> 14:00.960] When I work with a team, I would want them to already use a style guide without the automation. [14:00.960 --> 14:05.760] This is important because you can figure out what you want in your style guide, what should [14:05.760 --> 14:10.480] be taken out, and you can actually build a process. [14:10.480 --> 14:15.360] Once you're confident with that process, then it's time to automate. [14:15.360 --> 14:21.840] Second, you figure out how to deal with false positives. [14:21.840 --> 14:24.640] Style is going to be wrong. [14:24.640 --> 14:29.080] You're going to have to talk to your team and figure out what's going to happen when [14:29.080 --> 14:32.280] a tool gives you the wrong answer. [14:32.280 --> 14:39.360] I've had teams where they've gotten a false positive, and it really destabilized them. [14:39.360 --> 14:41.760] And so having that plan is important. [14:41.760 --> 14:45.200] And finally, this is the most important part. [14:45.200 --> 14:56.400] Communication will not solve for poor team communication, pettiness, and office bullies. [14:56.400 --> 15:02.720] You can't use CICD to deal with bullies. [15:02.720 --> 15:09.400] You actually need to talk to them, and you actually need a conversation. [15:09.400 --> 15:10.760] Thank you very much. [15:10.760 --> 15:15.360] You can find me at document rights on Twitter and YouTube. [15:15.360 --> 15:25.360] Wait, wait, wait, yes, okay, yes, we're going to run this. [15:25.360 --> 15:33.960] I'm sorry, wait, wait, we only have two or three minutes, so let's not do too much clapping. [15:33.960 --> 15:36.480] This is what the repo looks like. [15:36.480 --> 15:37.840] This is a bare bone. [15:37.840 --> 15:39.640] What I have is a getting started guide. [15:39.640 --> 15:42.920] I've used Obama Ipsum. [15:42.920 --> 15:45.840] You don't need to use Obama. [15:45.840 --> 15:51.480] There's actually a Trump one, too. [15:51.480 --> 16:02.600] So we have this, and get status, get ad, get commit, Obama example. [16:02.600 --> 16:08.480] I know this is not great, and then let's push this. [16:08.480 --> 16:14.200] So I am now pushing this to GitHub, which is here. [16:14.200 --> 16:19.200] So this is my GitHub repo, and here you see the workflows, the config file, the getting [16:19.200 --> 16:25.360] started guide, and this is where your actions are located. [16:25.360 --> 16:31.800] And to the left of your actions, in this example, I'm only using one action, but you can use [16:31.800 --> 16:37.720] many actions, and here I'm actually running the code. [16:37.720 --> 16:41.920] So it's still building. [16:41.920 --> 16:43.400] And how much time do I have? [16:43.400 --> 16:44.400] Do I have one minute? [16:44.400 --> 16:53.040] I have, oh, someone said two. [16:53.040 --> 17:00.400] So build, yay, this built, which is always a plus during a live demo. [17:00.400 --> 17:03.520] And if we scroll down, here are all the issues. [17:03.520 --> 17:05.640] So there are different levels. [17:05.640 --> 17:09.200] One level is an error, the next error is a warning. [17:09.200 --> 17:12.360] So error is spell out all ordinal numbers. [17:12.360 --> 17:18.080] And what I like about this is, let's see if this is going to work for us. [17:18.080 --> 17:26.880] This shows you exactly what your error is, and you don't need a person to comb through [17:26.880 --> 17:29.160] the documentation and tell you this. [17:29.160 --> 17:35.200] This is a linter telling you exactly what you should change, and your higher level problems, [17:35.200 --> 17:39.240] you can have a product manager or a technical writer deal with, and do we have time for [17:39.240 --> 17:40.240] questions? [17:40.240 --> 17:41.240] No? [17:41.240 --> 17:42.240] All right. [17:42.240 --> 18:08.640] Thank you, everyone.