Sorry for everyone who heard nothing.
So reading good documentation is easy.
I'd say deceptively easy.
You don't really realize you're reading good documentation.
You only realize when you're reading bad stuff.
Writing good documentation is easy to read.
It's hard.
That sentence, it was kind of hard to write and read.
I think I said it right.
And so I wanted to lay out a few things that I think make
good documentation and talk about how Vail helps me
achieve these.
So correctness, for sure.
Your doc should actually represent the thing that
they're documenting.
But I think that they also need to be clear.
And that means not using confusing language.
And also being consistent, I think, helps clarity.
So if you can enforce style across your documentation,
you can have your readers experience the same thing
wherever they are in your docs.
And they can scroll down this bit and find that information
given the text that they're used to see.
And also it needs to be inclusive.
And we're writing docs for people primarily.
I'm sure crawlers as well.
But people are reading these.
We shouldn't have cultural biases, stereotyping of race,
gender, or any cultural stereotypes in our documentation.
And accessibility is part of that.
I think from the Google Style Guide, the World Health
Organization estimates that 15% of people have an
accessibility need.
That's about 1 billion plus people.
And if you write with that in mind, not just that 15%
benefit, everyone benefits from more accessible docs.
So I'm sure, again, preaching to the choir, we all know what
a good doc should be.
But how do you achieve that?
You could use a style guide.
You could use one of the many style guides.
They're all huge.
And they all are constantly updated.
And you've got to pick one or many.
And maybe they're not perfect for your job.
And I think there's three major challenges for using them.
You've got to memorize all of those rules.
And there are too many.
Even our sort of smaller Grafana style guide, there's
too many rules to remember.
You need to be able to explain them.
And that's, to yourself first, justify the rule.
But also, when you're sharing knowledge with your peers, you
want to say, you should do this because not you should do
this.
You don't want to be punishing people, I think, of the
shellcheck linter for bash.
That esoteric language is awful.
But shellcheck kind of makes you feel like you're learning
how to write good bash.
So you want explanation of style.
And you need exceptions.
It's a creative task.
There's known exceptions for all of the style rules.
And then there are going to be times where you as a writer
or anyone as a writer might want to either subvert the
rule or just break it in a small instance.
So it's got to be easy to get out of these style.
You can't block your entire CI because somebody wrote in
passive voice.
So this is where Veil comes in.
And I'm going to let Veil speak for itself.
This is its own words for why he should use it.
It enforces your own style.
And it goes beyond traditional writing related rules.
And we'll look at how you can write your own style in Veil.
It understands markup really well.
So it doesn't matter if you're writing in Markdown or
ASCII Doc or Restructured Text.
You won't be suffering for that.
And you won't be punished for the special syntactic
elements in each of those language.
Veil cares about the pros.
So short codes in Hugo do not affect readability indexes
when you use them in Veil.
And it's 100% offline.
You never get sent to a remote server.
It's just a CLI tool that you can run in continuous
integration.
So you have exactly the same experience locally as you
would have in your CI.
Not that all cloud services are bad.
I think some are very important.
It's fast.
It can be used anywhere.
And yeah, in CI and CD.
So let's get started with Veil.
So Veil uses styles.
A collection of rules that you define or can borrow from
other packages.
And I'm going to talk a little bit about each of the major
extension points to introduce you to the kind of rules you
could write and then show you some of our Grafana rules.
And then we'll look at how you can set it up in a project
as well.
So the most simple rule is existence.
That is just, is this word somewhere in the page or in the
scope?
And perhaps you don't want certain words to appear.
This is when you would use that rule.
In a slightly extended example, if you want to replace that
word with another, you use substitution.
For Grafana, I think probably the most important one is
alert manager, which can be spelt at least four different
ways, but should only be spelt one.
Then you have occurrence, which checks that you have a
minimum or maximum number of times of an occurrence of a
token.
I haven't written any rules for this yet, but maybe you want
to make sure you say please a certain number of times, but
not too many times so that the compiler cares.
Consistency.
So this one is pretty useful for if you've got that
British-English, American-English divide.
But also other words can just be confusing, like advisor,
advisor.
I'm not actually sure which side of the Atlantic, which one
is correct.
And this just says, if you've used one in the document, you
can't have used the other.
So just stick with one of the two.
We do use US-English in ours, but that you can enforce with
dictionaries as well.
Conditional is most commonly used for abbreviations, I
would say.
If you present an abbreviation in the doc, you need to have
first explained it elsewhere.
So you can write rules for exactly that.
Capitalization, headings typically have sentence
casing.
Well, they do at Grafana.
You can also enforce title casing.
I don't think you can enforce arbitrary programming
casing, like snake casing, pascal casing.
Maybe.
I haven't tried to write the rule yet, but haven't
needed to.
And then sequence.
I think this is one of the most powerful ones that I
haven't yet used.
Vale tokenizes every word and also applies the natural
language token to each of those words, too.
So you can write rules that are not just don't use that
word, but don't use an adjective and a noun in
this particular grammatical context.
I've not written any yet, but it helps you write much more
appropriate rules with fewer exceptions than if you're just
focusing on the raw text.
And finally, if none of these are suitable, there's also a
scripting language in the Tango scripting language, and you
can use that for arbitrary logic.
And I skipped one, which is metric.
There's a bunch of built-in variables that Vale exposes
like the counter words, the number of syllables, the
number of sentences, paragraphs.
And you can use those to implement
readability indexes.
I think all of the major readability indexes are
already implemented in some form.
Cool.
So whistle stop tour of pretty much everything you can do
to write your own styles.
I thought I'd show off a couple that we have at Grafana.
This one just checks.
It's one of the most simple rules for the existence of the
word will and says, don't use that.
Engineers have a habit of talking about what a
process will do when it's actually doing it.
So we should talk in the present tense.
And I think this highlights, so first I can talk about the
structure here.
It's a YAML file, so not only engineers can write it, but
technical writers, every contributor.
You may have reservations about YAML, but it is a lot of
places, so a lot of people can read and write it.
This one extends the existence rule.
It sets a warning level, which is one of the three levels
you can have.
Suggestion, warning, and error.
Typically, what my recommendation would be, have
suggestions on when you're developing locally, but don't
let CI block on that.
Again, passive voice is not a reason to not build your site.
But you might want to be reminded that, yeah, you just
keep writing in passive voice.
Here we provide a link to the reasons for the existence of
this rule.
Grafana, we default to the Google style guide, but have
our own rules as well.
So in this case, the Google style guide is exactly what we
do.
And the message field, I think, is the most important, going
back to explanation.
This is your opportunity to tell your users why the rule
should exist.
And so when the bot in CI says you've done a thing wrong,
they hopefully can understand why they should make the
change.
My experience with bots is actually the
opposite of yours.
I feel like if I were to say, in a poor request, please,
could you do this, people will listen.
But if a bot says you've done this wrong, it feels like a
punishment.
So I'm trying to make the bots as friendly as possible.
And so you've got to write friendly messages.
And there's substitution in there as well.
But we've only got one token, so that percent s is always
will in this rule.
We've got a slightly more complicated one here, which
extends substitution rules.
And we've agreed at the company to use dialogue box
instead of modal or Google recommends dialogue.
But I feel like more generally, people understand the
window that pops up as a dialogue box.
This one, because the Google style is different, we link
to our own open source documentation, right?
This is the first tool kit, where we have our entire
Grafana style documented.
And this rule has a swap field, which says if you see the
thing on the left, replace it with the one on the right.
Dialogue box appears.
Should be dialogue box opens.
A modal should be a dialogue box.
And then a nice feature of Vale is it's written in go,
which means RE2 syntax for regular expressions, except
they've also extended their engine with a positive look
head, negative look head, and their look
behind equivalents.
So you can write much more expressive rules more easily.
So this says look for dialogue as long as it's not
followed by box, and replace it with dialogue box.
Cool.
How do I do for time?
I'm rushing a little bit, I think.
14 minutes.
OK, well, we'll just have time for questions.
So let's configure Vale for a project.
This is the configuration file.
And I think this shows the difference between what you
expect the engineer to work with and what you expect all
your other contributors to work with.
Vale uses YAML for its rules, but it uses INI files for
its configuration, because that's what the engineers have
to write.
And it's a better format.
So here we've got a definition of packages.
These are all preexisting styles that you can use, and
immediately start linting your documentation with.
I've put a bunch up, Microsoft, Google, Red Hat.
Hugo is a config package, which I haven't talked about in
this presentation, but it tells Vale how to ignore certain
Hugo tokens, like the syntactic elements that are not
important to the language.
And shamelessly, I've put the very, very first release of
the Grafana style up there as well if you want to use it.
You can set many, many other configuration things, but here
is the minilevel is set to warning.
And styles path is where Vale stores the packages when it
gets them, because it's got a handy command to just pull
these for you, so you don't have to worry.
And then that final section is how you control individual
rules for different file kinds.
So in this case, I say all files are treated the same.
I say use just the Grafana style.
So even though I've collected all of these packages, I'm
only concerning myself with the Grafana one at the moment.
And even though this is nonsensical, I wanted to show
how you would turn off a rule globally if you wanted.
So this is turning off the exclamation mark rule for
Google.
Since I'm only using the Grafana style, that's not
important anyway, but replace Google for Grafana, and it
would do that.
Cool.
So demo time, just so I have an excuse to get Emacs out.
Can I make this full screen?
Cool.
And well, that's the whole demo spot there.
If I hit here, we're in the directory.
And you can see I've got a test file.
I've got my veil.ino file.
I've got a hidden folder, which is where veil's storing
its stuff in case the network goes down.
And I can't sync and then get, because everybody should be
doing Docs' code.
Sorry, I wrote this talk prerequisite, sort of like
Docs are already code.
So it's good that we followed from the DocOps talk.
So here's my test file.
And I have written a markdown file that says, testing the
veil.
Then to whoops, I've made a typo.
Grafana is cool exclamation mark.
All of those things are true.
And here is my actual configuration for veil in this
little repo.
I'm going to pull the Hugo one.
I didn't use any Hugo, but it's just default for me now.
I'm going to pull the Google package.
And I'm also going to use that Grafana style that I've got.
I'm going to include suggestions, although I don't
think I made any suggestion mistakes.
And I'm going to use both of those styles in this.
So I can head back to the command line.
And I can run the first command, veil sync.
And that's showing up OK.
So this is how you get all your packages.
It's very easy.
Now I can suddenly lint all of my documentation with all of
the Google style guide.
And I'm going to run it on that test file.
And here's the output that kind of exists on that title
slide.
You can see it's quite human readable.
It tells you the rule on the right.
It tells you exactly where it is on the file on the left.
And then it gives you the message.
It's very human readable.
It's not very machine readable.
There's other output formats that are machine readable.
So if you want to do things with this output, you would use
those.
You can also, I think, provide go templates and do very
expressive output with that.
Cool.
Let's go back to the presentation, which is in here.
Where is my presentation?
There we go.
Cool.
Right.
So I wanted to talk a little bit.
I know this is about veil.
Thank you.
About an additional tool, DocOps tool, ReviewDog, which if
you are trying to introduce style to an organization that
has documentation a lot, or even a little, but certainly if
it has a lot, you need a way of making those changes
incrementally.
And you could do that one rule at a time across the Docs,
but that's quite painful too.
Or you can do it as people make changes.
I only want to make sure that anything new is conforming to
the style.
And hopefully, eventually, everything gets churned and
you now have perfectly styled documentation.
And ReviewDog lets you do that.
It's a command line tool again, similar to veil.
You don't need to run it in the cloud.
You can run it locally and in CI.
And it takes as input, linting output from any tool.
And it is also aware of unified diffs.
And I'll talk a bit about that.
And it can comment on all of the major forges, so GitHub,
GitLab, others that I can't remember the name of.
And you can tell it to post comments on pro requests.
So you can get that response automatically.
Almost human response.
It's got a little icon.
Especially in GitHub, it will give you suggestions as well.
If you provide ReviewDog the action to fix the problem, it
will post that suggestion automatically for the user.
And it knows about diff context.
So if you've only added and modified these three lines, it
will only comment on those three lines.
It will ignore the swans of other linting output that
Veil might have thrown.
I can show you a little picture of what that looks like.
This is on GitHub.
It's not documentation, but it's a bit of linting from
Golint.
If that was a formatting thing, it could tell you to, it
would give you a suggestion.
You can just commit a suggestion.
Hayabusa is the lead maintainer of this project.
And I think, so going back to the CI part, one of the other
powerful parts of ReviewDog is that if you've got CI jobs,
or if you've got generated files or formatted files, the
CI workflow just becomes run that thing, that generation in
CI, and then tell ReviewDog about it.
Because it just runs a diff on the Git directory and uses
that output to give you the suggestions automatically.
So you don't have to write any of that glue.
So I wanted to throw a shout out to Joseph and Hayabusa.
And also everyone here that has contributed to Veil, it's
been brilliant using the two projects.
And I wanted to thank everyone here for coming.
I did not expect it to be a full room.
I should have done.
We have some plugs here.
The right is Toolkit that Grafana uses to maintain its
style.
If you want some pointers for style, I think that's a great
place to start.
It's an open source repository.
If you do use it or have any issues with it, do raise them
there and we'll try and fix them.
And also as a company, we have a Docs channel in our
community Slack.
I think that's everything.
So a little quick, but plenty of time for questions,
hopefully.
Thank you.
Thanks.
Thanks, guys.
Thanks.
All right.
There's one right over there.
The question is, how do you suppress warnings?
So for example, I'm using exclamation mark and I have very
reason for using it.
Yes.
And can I do this while I make specific comments and ask
you, Dr.
I'm so glad you asked that question.
So the question is, I have broken a rule in my document
and I want to tell Vale ignore that instance.
I did it on purpose.
And in my review note, in my speaker notes that I didn't have
up, I had exactly this covered.
So Vale, you can turn off individual rules for individual
files.
You can turn them off globally.
But I see your head go down.
But also it knows in each of the source files the comment
syntax.
So in markdown, which is the one I know best, HTML comments
that have a special form, Vale rule equals no, turns it off
at that point.
And then as soon as you re-enable it with another HTML
comment, it can restart.
So you can isolate single lines.
And with things like markdown, that's usually enough.
And so you can turn off individual rules for very
specific cases.
Thank you.
I think I've missed the point of using review dot.
Because if you can integrate Vale in SSS in smart
terminal, why would you use review dot?
That's true.
Yeah, so.
Can you repeat it for people there?
Of course, yeah.
So the question is, given that you're running Vale in
continuous integration anyway, where does review dog
provide additional value?
And for me, that's in the sort of conversational nature of
the tool.
I worked primarily in GitHub.
And that framework of reviews on poor requests allows the bot
to, instead of having CI feedback in, you know, you go to
this tab or this check or your different CI system and find
the error, you get it on your poor request in the same way
that I as a maintainer would do if I remembered the rule
myself.
And I would say, please do this or here's a suggestion.
And I think having that feedback in your forge, whether it
be GitHub or GitLab, is more effective than going out and
finding it in a bread.
You're right.
I hope that because you can do that.
And maybe, for example, you can.
Yes, yeah, absolutely.
Yeah.
You can use the comment action in GitHub, yeah.
Exactly, yeah.
Thank you.
Another question.
Congratulations on surviving your first time.
Yeah, thank you.
I'm very sweaty.
We'd like to some style guides and show how they can be
imported.
And you also mentioned the Chicago banal style.
Is there a Vale plugin for the Chicago banal style?
I don't think so.
Yeah, I think not yet.
But they are.
I think people have asked that.
And I think it is under copyright.
Well, it's obvious that the copyright has been passed.
We have touched this subject before and had problems.
So I will remind myself to look into it again.
Yeah, so I should say that the packages of style guides
you've seen, like the ones that you've seen,
the ones of style guides you've seen,
like Google and Microsoft, are themselves openly licensed
in a way that Vale can write those rules.
I don't know how many people have contributed to the production
of those styles, but there's a lot of rules across them.
And I didn't even demonstrate, I think, half of the sets.
There's one specifically for accessibility kind of concerns.
There's one that's got some very odd rules about certain language
that you might not want to use in job posts.
But if you don't want to see bro in your language,
then you can use job lint for that.
Or, of course, write your own ones for anything you're missing.
I think I have time for one more.
OK, yep.
Oh, I saw you first.
Sorry.
No, they're here.
We have a lot of, or we have almost only non-native English speakers
in our documentation.
That's something that Vale can help with,
because we see that for language group,
you see certain patterns which make it very difficult
for another language group to understand.
So having a lot of non-native speakers writing your documentation,
is that somewhere that Vale can help?
And again, my speaker notes, so next time,
I'll make sure these are available.
I wanted to talk about the importance of the privilege I have
as a native English speaker and how I find it hard to write documentation
and the additional challenge of being a non-native English speaker.
I think that's why you've got to be compassionate in the rules.
You can definitely write rules that are specific to those patterns
that you might see in non-native speakers English.
We have one to that effect, I think, like allows to,
is commonly come up, so we have allows you to as a replacement.
And you want that to be fed back to the contributor
in a way that is not punishing,
but helps them know that they are writing a better form of documentation.
So thank you very much.
Is there a single second more?
I was wondering, do you know if people are also using Vale
to style-link comments in code?
Oh, are people using Vale to link comments in code?
I've actually been asked that once already today,
and I don't know the answer.
They are.
Yeah, brilliant.
Because there's been lots of issues about people
asking for certain configuration fit to do that.
Brilliant.
So yes, definitely is.
Cool.