I'm going to give a warm applause.
It's your time.
Great.
Thanks, everybody, for joining me this morning.
My name is Fiona Pierce Artiaga.
I am the director of technical writing and documentation at Grafana Labs.
We at Grafana have a really strong history of open source projects from Grafana,
which I think is our most well-known, to Loki, Mimir Tempo, Pyroscope, Bela, Faro,
and of course the entire IRM suite built off of our open source alerting project.
As a result, we have a lot of experience with maintaining open source documentation,
and we've learned some lessons along the way.
So I'll share with you how this approach works in our company,
as well as other companies that are in the open source community that I've worked for.
I won't have time for questions today, but I will be outside afterward,
and I'm more than happy to talk about documentation.
I've winnowed this talk down as much as I possibly can,
but I have loads to say on this topic,
and I think there's always loads of questions about it.
So when we look at an open source community and a commitment to maintenance,
the gap that I'm talking about in mind the gap is the difference between
what you hope your documentation will be and where it currently is.
And wherever you are in your journey, I think you'll find these tactics and strategies useful.
So it really breaks down into three major areas.
You need to communicate, you need to minimize friction with your developer community,
and you need to engage.
So when we talk about minimizing communication,
there's really things that I found work extremely well,
and there are things that I would recommend not doing.
The first thing you need to do, and this may sound really self-evident to you,
is an open source project maintainer,
but you need to tell your community what you need,
and be explicit about the types of content that you find valuable,
and why it is that you think it would move the project forward.
In addition, you need to tell them how.
Provide them with guidelines, give them examples, give them models, give them samples,
because otherwise they're flying a little bit blind,
and the PRs that you potentially receive may not be of the quality that would help your project.
But on the topic of guidelines, you need to make sure they evolve.
If they're brittle, you'll find that your contributor community will not feel embraced,
it will not feel kind,
and it's very important that the community feels welcomed and acknowledged
in the process of making your project better.
Things that we find don't work.
Don't walk into this conversation with assumptions.
Just because in your head you know what the project needs doesn't mean your community does.
So say it out loud, put it in your readme, put it in a GitHub issue with Help Wanted.
Add to the Help Wanted projects on GitHub itself.
Go into a blog, if you have a website, publish it on your website.
If you're doing a FOSDEM talk, you know, Thomas just mentioned at the end,
contributions are welcome because making documentation better improves the project,
not just for you, but for everybody consuming that tool or new technology.
If you have a readme, make sure it's fresh.
Otherwise, your contributors are following the guidelines that they thought were the right things to do,
and if they're encountering difficulty moving the documentation contribution forward,
it might be because you haven't told them properly how to do that.
Have guidelines.
If they're not present, people don't know what to do, and evolve them.
Minimizing friction.
I cannot say enough about the value of writing docs as code.
We use a docs as code method, Acrophana.
That means we use a source control product, GitHub.
I think that's becoming the standard.
We use an open source IDE.
For most of us, we use Visual Studio Code.
We also use a Veil Linter.
If you attended one of my colleagues talks yesterday, we're improving the Veil Linter to follow the
Grafana writer's toolkit guidelines that we've created.
And make sure that the tooling and the tools that you engage with for documentation align with the tools
that your team and your project maintainers are working with.
When you begin breaking the documentation away from the project, if you put it into a CMS,
or if you put it into a separate repo, you will find that the documentation regresses.
It's just human nature.
The minute you move the docs away from the code, it's not considered a maintenance project anymore.
It's considered an other thing to do, potentially an afterthought.
And if you're using a carrot and stick method, where your stick is that you're linting
and you're making sure that the markdown file is associated with this new code is being updated,
you have no way of enforcing that in your CI CD.
So while CMSs and XML DEDA may seem really cool,
I would highly recommend from my experience that you use markdown, GitHub,
some kind of IDE like Visual Studio Code.
You'll find that maintenance is much easier because you've minimized the friction to contributions.
Engagement.
So you've told people what you need.
You've given them guidelines.
You've given them samples.
You've given them models.
You have used the tools that they are also using.
Don't leave them alone.
Engage.
If you see a PR that comes in from an outside contributor,
make sure you respond to it in a pretty timely fashion.
That could be two weeks, but maybe it's not six months.
Documentation, additions, and PRs are very, very often the stepping stone into your project.
It's when a contributor is checking to see whether it's a welcoming space,
whether their contributions would actually add value.
The number of typo fixes that we get, because we're not perfect in our technical writing team,
the number of typo fixes we get is actually quite large.
And it's because users know that that's a quick and easy fix.
So as soon as they've given this contribution to you, welcome them.
Take their contribution.
And the next thing you know, they may have built you a full tutorial.
They may have updated all your reference documentation.
They may have done something really amazing to move your documentation forward.
But if you leave them like the Cookie Monster here in this GIF,
they're never going to come back to your project,
because it doesn't feel like it's a safe and welcoming space.
On the other hand, there are times when you receive a PR and you're,
you know, it's just not necessarily the right thing to spend time on.
It's a really hard decision.
In an open source environment, we like to think that every contribution is welcome.
But there's two major areas where we say, you know, this isn't really particularly valuable to the project.
One is when the work to make that PR of a high enough quality to produce and publish
is greater than the value that's being brought in the PR itself.
You can engage with your contributor, point them to your guidelines,
see if they can rectify the PR on their own.
Or you can delve in and do the full edit.
But sometimes you don't have time for that,
and sometimes it's not as valuable as you would like it to be.
So in those situations, be kind, be respectful, but you may close the PR.
The second thing that we have found sometimes occurs is we will have a contributor who comes forward
with a very distinct perspective that may not align with what we're trying to accomplish with our documentation,
or is adding information that may work on their machine, but doesn't work on ours.
And again, be kind, be respectful, and often those things will turn,
but sometimes they won't, and in that case, close the PR.
My main message here is don't let things linger.
If you've decided that this is not something that's going to be valuable to your project,
respond and close the PR.
It's part of the process of engagement.
If you leave those things open, the community will feel like,
well, I don't understand why this isn't being moved forward or what's happening with it.
So make sure that you're pretty responsive within a reasonable timeframe,
and reasonable will vary according to the project.
Data really helps in determining the know.
We have a wide variety of data that we look at where Grafana is an observability monitoring company.
Unsurprisingly, I have a dashboard that I look at on a really regular basis.
But when you're just starting out, these are the key items that I would recommend that you look at.
You want to make sure that you're looking, if you have a website, the number of visitors to a page
that will help determine your top 10 and where you probably want to start if you're looking at maintenance issues.
You also want to look at time on the page, and this is a bit of a subtle data point.
Some pages that you write are going to be specifically created for users to move to something else,
so you don't want them to spend a lot of time on the page.
But if you have a page that's quite detailed and has a lot of information,
and users are bouncing off of it in 35 seconds, there may be something wrong with that page.
And you might want to create an issue and put a help wanted note on it so your community can help improve it,
or give you feedback on why it is that they're moving so quickly away from the content you've provided.
Data of Last Update helps you know how stale your content is.
And some open source projects actually will put in the front matter of their files a date of Last Update
and run a cron job on a monthly basis to see if something's six months or more out of date
and check in with the subject matter experts or the maintainers of that page and ask them,
does this need to be updated? It's been a while since you last looked at it.
And then also look at your accessibility scores.
And by accessibility, I mean how quickly the page loads and other elements such as the use of the color
and whether or not it renders properly on mobile.
So, seven lessons learned. I've been working in technical documentation for a couple of decades,
so this is a very short list and I'm happy to talk about other lessons learned.
Number one lesson is one big swing will not get you far enough.
And one big swing refers to in many projects, people realize the documentation is drifted
and they'll decide, okay, we're going to have a two-week time period or a three-week project
where we're all going to dig in and work on the documentation
and it's going to be fabulous at the end of this.
We've done this a couple of times at Grafana and it has failed.
And it hasn't failed because people don't have good intent.
It hasn't failed because they don't have information of their fingertips about what needs to be updated.
It's failed because one big swing will not take you far enough.
You will get distracted from the project, you will work on something else,
you will get a customer escalation, someone might take PTO.
If documentation maintenance is not already part of the culture of that project,
fixing it in a one-time go is not going to improve it.
But that's actually a really valuable lesson because what that helps the project maintainers understand
is, wow, we kind of thought we could get this done in a two-week period, three-week period,
and now we recognize that we need to incorporate it into our daily business and into our daily updates.
So that in and of itself can be quite a valuable exercise.
If you're overwhelmed, like where do I start?
I have such a wide swath of content that needs to be updated.
Help your users get from zero to one.
It sounds kind of basic, but start with the beginning of getting started.
Make sure that you have a really watertight get started.
Once users have gotten started with your project, they'll be much more forgiving of other areas that need better content.
And they'll probably help you.
Maintenance really only works if you have a commitment to open source documentation that lives in an open source project.
When you move the documentation out, you will see that the documentation begins to regress.
Linting, using something like a veil linter, is your friend.
It helps move the PRs through more quickly.
It helps identify more quickly for contributors where they haven't met a guideline,
and it removes some of the toil of making that PR good.
Guidelines increase your contributions.
People know how to help you.
They know where to go for guidance and samples and models.
But make sure you're being flexible with those guidelines and hearing what the community is telling you.
When we wrote the Writer's Toolkit about a year and four months ago, we've iterated on that toolkit a number of times.
It's an open source project.
We're happy to have issues and PRs opened against it.
We've definitely course corrected in a couple of areas because we thought something was going to work.
It didn't work as expected.
And remember, it's okay to say no.
After you've gotten everybody off and running on your project and they're really excited and you've told them how to do it,
if the PRs still aren't good, it is okay to say no.
That's it.
Thank you so much.
Okay, thank you for the talk and you are available outside for questions.
Here's this.
I don't know.
Thank you for your talk.
Thank you so much for the introduction.
I appreciate you for heralding and volunteering your time.