My name is Portia, I'm from Document Right, we write technical documentation and today's
presentation is called Automate the Pain Away, CICD Workflows for Documentation, so once
again, it's me, I run a technical documentation agency, before then I used to work as a Django
developer, I spent years, too much time tinkering with side projects and working with documentation
and you can find me on Document Rights, on Twitter and YouTube.
What we'll cover, what problem we're trying to solve, the tools that exist, how to automate
your docs and the pros and cons to automation.
So I talk to clients and a common problem they tell me is, sounds like a developer wrote
the docs, I'm like, okay, and we dig into exactly what does that mean, sounds like a
developer wrote the docs.
So some of the problems that companies have with their documentation include a wall of
text, which means it's really hard to parse through the documentation, it lacks context,
this is really common because if you wrote the code, you really don't know what an outsider
will be like confused on, it's out of date, it's not updated on a regular basis, the documentation
is incomplete, there are some features that lack documentation and finally it's incohesive,
it's very obvious that your Go developer, your React developer and your marketing person
all worked on the documentation and you can tell which section they worked on.
So quick tour of voice and tone, if you want your documentation to sound cohesive and not
like four different departments touched it or sound like developers wrote it, it's really
important to know these concepts.
So this is a voice chart and the purpose of a voice chart is to make sure that your documentation,
like I said before, sounds cohesive and this is based on different principles.
So you get together with your team and you figure out what do we stand for and based
on what you stand for that actually informs the concepts, vocabulary and grammar that
you will use in your documentation.
I can talk about this but it's easier to actually give you some real examples.
So this is Google's voice, this example I'm using comes directly from Google's documentation,
I promise this is not my opinion, this is just Google.
So if you're looking at Google's documentation, they tell you that some of their principles
include timeless documentation, catering to a global audience and accessibility, that's
all nice and good, but what does that mean?
For concepts with timeless documentation, it means it's avoiding words and phrases that
anchor documentation in a point in time, like 2015.
Vocabulary, it avoids words like now, new and currently, that's in their style guide
and grammar, it uses the present tense.
So you take your principles and from there, you actually figure out what concept are you
going to use, which vocabulary are you going to use and not use and what is your grammar
going to be like.
Second example, Microsoft.
This comes from Microsoft's style guide documentation, once again, I've not made this up, these are
not my principles.
Warm and relaxed, crisp and clear, bias free communication.
So if we look at crisp and clear, it means that we're to the point, we write for scanning
first, reading second, we make it simple above all, vocabulary, whenever possible, choose
words that have one meaning as opposed to words with multiple meanings and grammar, make
every word sentence count, concise, clear sentences.
So once again, it's easier for you to get to concise, clear sentences, it's easier
for you to get to whenever possible, use words that have one clear meaning when you know
what your principle is, that's something that should not be avoided.
We talked about voice, there's also tone.
So you can have a voice, but you can have different types of tone for a voice.
So if you have a warning label, you'll have like, it'll be urgent, you have an urgent
tone, but the voice is the same.
If it's empathy, like a getting started guide, you want that person to feel like, yes, they're
welcome, yes, they should spend their whole weekend with your documentation, whole weekend.
And inclusiveness, the introduction is also welcome.
This is what we're about, yes, this documentation is for you and will solve your problem.
Those are the different tones.
And once again, you have one voice, but several different tones in your documentation.
All of this is codified, not in the product manager's head, not in the lead engineer's
head, but in a style guide.
So the examples that we looked at were from Google and Microsoft style guides.
So there's several different style guides that you can use for technical writing.
There's a Google, Microsoft, Smashing Magazine has one.
And the one that I personally use for my team is Digital Ocean.
I love Digital Ocean's technical writing guide because it gets to the point, and it gets
the information really quickly.
If you're using Microsoft style guide, it's literally over a thousand pages, literally.
And I think Google is around over a thousand pages as well.
So even with the best intentions, one just doesn't have time for that.
Here is a list of common documentation pitfalls.
This data comes from the Google season of docs 2021, and some of the pitfalls that you
have of documentation include the documentation is lacking, specific use cases, the documentation
is disorganized, it's outdated, not consistent.
You don't know of these problems, right?
Your documentation's perfect.
And the documentation needs to be converted into a different tool, platform, or format.
Oh no!
So many moving parts!
No wonder why no one keeps up with their documentation.
You have voice, you have tone, you have the fact that it's out today, you have the fact
that people are using different tools, how do you keep it together?
Automation to the rescue!
So this is where we're going to use CICD tooling and automation to make sure that we take our
principles and best practices and actually implement them.
So we're going to take a step back.
Using a CICD workflow is part of a docs as code workflow, and with a docs as code workflow,
it has several parts.
One, you're using version control like Git.
Second, you're building documentation with an open source platform like Spinks, Gatsby,
Next.js, Docsaurus.
The documentation is written in MDX or Markdown.
I know there's some ASCII people out there, but in this presentation we're going to talk
about Markdown, and you make use of CICD tools.
If you want to learn more about docs as code, you can read Anne Gentel's book, Docs Like
Code.
Her first edition was 2016, and she just updated it actually last month.
She's amazing.
I love that book.
I'm going to read it to everyone.
All right.
Automating your team style guide starter pack.
So in this situation case, we're going to use GitHub Actions, Markdown, and Veil.
I'll talk about what those tools are.
So GitHub Actions, the basics.
It's a CICD solution provided by GitHub.
It's made up of workflow and events.
It contains a marketplace of third party actions, so you can write your own actions, but you
can also use actions that are already pre-written in the marketplace.
And it's great for running linters and tests.
Many of you probably already use it for JavaScript and Python and other programming languages.
Markdown.
It's platform agnostic.
Use it with platforms such as Gatsby, Hugo, or Docosaurus.
Not as complex as code.
I put this down because many people who are touching your documentation, they're not always
engineers.
And in our team, we have a project manager, and she did not know anything about Git.
She knew nothing about code, but she actually updates documentation using Markdown.
Another thing I like about Markdown is you can use MDX, and MDX is where you can import
and use React components.
So if you want something that is interactive, MDX really gives you some more flexibility
in MD.
Veil.
It's not a linter for pros.
There are extensions for Visual Studio Code, JetBrain, and Vim, and Emacs fans out there.
It's not the only linter out there.
You can check out Woke and WriteGood.
The one thing I will say is with Veil, you can use many linters within Veil, and Woke
is what it sounds like.
I'll let you check that out on your own time.
The code.
So I'm going to, let's see.
If we have time, I would love to run a demo, but we'll see what happens.
And I would have to use a second screen, so let's just stay with this for now.
This is the Veil config file, and the Veil config file, what you're looking at is the
style path, the alert level.
I believe there's three different alert levels.
All kind of format you're using, which is markdown, and style guides.
In this case, you're not writing your own style guide, but you're using style guides
created by WriteGood and Google.
And this is what a typical workflow looks like.
This is the Veil one, and you have on, which triggers the workflow.
So the trigger is, in this case, a push, and this code will run on a main branch.
You're not stuck on one branch, like if you want to run this on multiple branches, you
can, but in this situation, we're just using one branch.
And if you go to 25 to 27, those are the style guides that we're using in this situation.
We're using Google, and we're also using WriteGood.
I just added this today, because I don't want this to seem like magic.
When you're using Google's Veil YAML file, this is what it looks like.
It's basically a regular expression, checking this.
This is the first person one, and it's checking to see if you're using I.
What you could do is, if you want to make your own Veil, linter, you can go to Google.
You can go to Microsoft, and you can use their examples to help you get started.
Finally, takeaways.
The benefits of automating your documentation.
It greatly speeds up the publishing process, which is a plus.
The git increases workflow transparency.
Git blame.
It encourages developers to take a more active role in maintaining documentation, because
it's using the similar tools that developers are using to develop code, which is Git, Vim,
MDX, and it upskills technical writers.
There are many technical writers out there that are not software developers, and they
ask a developer, well, what do I need to know?
What kind of coding skills do I need?
And they're like C++, which is fine.
It's fine.
But we're not giving them the kind of advice they need to use this on a day-to-day basis.
So if you go to Twitter, if you go to LinkedIn, if you go to write the docs Slack channel,
there are technical writers who want to know how to upskill, and knowing how to use markdown,
knowing a sprinkling of HTML, CSS, JavaScript can really give them the skills where they
can actually use this on the job, which is really important.
So you have these coding skills that they could actually implement, and that's one
of the reasons why I like the docs as code.
Caveats.
These are the cons.
When I work with a team, I would want them to already use a style guide without the automation.
This is important because you can figure out what you want in your style guide, what should
be taken out, and you can actually build a process.
Once you're confident with that process, then it's time to automate.
Second, you figure out how to deal with false positives.
Style is going to be wrong.
You're going to have to talk to your team and figure out what's going to happen when
a tool gives you the wrong answer.
I've had teams where they've gotten a false positive, and it really destabilized them.
And so having that plan is important.
And finally, this is the most important part.
Communication will not solve for poor team communication, pettiness, and office bullies.
You can't use CICD to deal with bullies.
You actually need to talk to them, and you actually need a conversation.
Thank you very much.
You can find me at document rights on Twitter and YouTube.
Wait, wait, wait, yes, okay, yes, we're going to run this.
I'm sorry, wait, wait, we only have two or three minutes, so let's not do too much clapping.
This is what the repo looks like.
This is a bare bone.
What I have is a getting started guide.
I've used Obama Ipsum.
You don't need to use Obama.
There's actually a Trump one, too.
So we have this, and get status, get ad, get commit, Obama example.
I know this is not great, and then let's push this.
So I am now pushing this to GitHub, which is here.
So this is my GitHub repo, and here you see the workflows, the config file, the getting
started guide, and this is where your actions are located.
And to the left of your actions, in this example, I'm only using one action, but you can use
many actions, and here I'm actually running the code.
So it's still building.
And how much time do I have?
Do I have one minute?
I have, oh, someone said two.
So build, yay, this built, which is always a plus during a live demo.
And if we scroll down, here are all the issues.
So there are different levels.
One level is an error, the next error is a warning.
So error is spell out all ordinal numbers.
And what I like about this is, let's see if this is going to work for us.
This shows you exactly what your error is, and you don't need a person to comb through
the documentation and tell you this.
This is a linter telling you exactly what you should change, and your higher level problems,
you can have a product manager or a technical writer deal with, and do we have time for
questions?
No?
All right.
Thank you, everyone.