I originally gave this lightning talk to a community of Salt developers at the October 2020 Salt docs jam, which was one of the first community doc events I had ever run. I reviewed this presentation recently and thought it might be worth sharing with more people.

I’ve repeatedly observed a phenomenon that I call the documentation gap in open source projects. To illustrate what the documentation gap is, I want to cite some statistics from a few open source surveys.

In 2017, GitHub conducted a survey with 5,500 randomly sampled respondents sourced from over 3,800 open source repositories on GitHub.com and other platforms.

• One of their key findings was that incomplete or outdated documentation is a pervasive problem, observed by 93% of respondents—so this pain was felt almost universally.
• And yet, 60% of contributors indicated they rarely or never contribute to documentation.

So, stated another way, nearly everyone thinks that good documentation is important but only 40% of contributors actually work on it. So, there’s a gap there.

We see this phenomenon in other studies. Take the 2019 Tidelift managed open source survey, which surveyed 400 professional software developers and DevOps professionals from a variety of company sizes:

• In this survey 72% of respondents said that established policies and documentation were a key factor when deciding which open source packages to use.
• And yet in that same survey, they found that developers spent less than 9% of their time on documentation tasks.

I need to add a disclaimer here. This 9% statistic is a bit of an inference on my part. In the section of their survey that asked how open source developers spent their time, documentation didn’t even warrant a slice of their pie chart, so 9% includes their “Other” category as a catch-all for miscellaneous tasks. I’d assume working on documentation fits somewhere in that 9%.

Anyhow, the point is that there is yet another gap here: 72% of them say documentation is important and yet they spend 9% or less of their time on it.

While researching for this talk, I stumbled upon an article by Rich Bowen, who is the community liaison for RedHat’s Apache web server project. He writes:

There’s common wisdom in the open source world: Everybody knows that the documentation is awful, that nobody wants to write it, and that this is just the way things are.

I want to bookmark this quotation because he goes on to say that this is a misconception, but it’s worth just acknowledging that this attitude exists in open source.

But he’s basically saying the same thing I’m saying: there’s this pervasive belief that documentation needs to be improved, but that nobody wants to do it.

So, why does this documentation gap occur?

To me, this looks like a classic value-action gap.A value-action gap is a psychological phenomenon where people act in a manner that is inconsistent with their personal values. Value-action gaps occur when people act in a way that fails to support their values, or in a way that contradicts those values entirely.

In the context of open source, we do value documentation. We all know:

• That good documentation reduces the amount of time it takes for new users and contributors to onboard, which is good for our community and reduces our workload.
• That it takes less time to read a good explanation of how the code works rather than examining the code itself to figure out how it works.
• That good documentation cuts down on time spent resolving support-related issues, which reduces the time we spend maintaining our project and frees us up for more important tasks.

And yet it’s hard to make time for documentation tasks, right?

But before we beat ourselves up about that, let’s remember that the value-action gap is not purely an open source problem. The value-action gap is a well-studied universal feature of human psychology that has been with us from the beginning and which will always be with us. It’s part of what makes us human.

For instance, the value action gap is the same psychological phenomenon that keeps us from:

• Exercising regularly
• Eating healthy
• Disciplining ourselves to go to bed on time rather than play on our phones or watch Netflix.

The good news is that this is a well-studied phenomenon in social psychology and so we can use the lessons about human behavior that these researchers have discovered in order to overcome this problem.

The research says:

• People’s values rarely translate into actions without taking active steps.
• You must deliberately translate your values into intentions, then translate those intentions into concrete actions.
• Build good patterns that make it easier to act consistently with your values and remove any obstacles that get in the way.

For example, we all value being physically healthy, but having that value alone doesn’t necessarily mean we will just magically exercise or stick to a healthy diet on our own. The people who are more likely to successfully exercise are those that deliberately and consciously examine their lifestyle and take a close look at what they personally find motivating and demotivating:

• Let’s say you learned that you’re better at being accountable to other people than you are to yourself. One way you could build a good pattern into your life is to set up a regular time to meet your friend to exercise in the morning. That way you’re accountable to someone.
• Let’s say you learned that chocolate is a barrier for you when it comes to eating healthy. Maybe that means you remove that temptation from your life by making sure you never had chocolate in the house.

With that in mind, let’s take just a moment to talk about how to remove barriers and develop good patterns for improving documentation. I’m going to mention four tricks you can try to get yourself to contribute to documentation.

Break down the line dividing tech writers from developers

Every once in a while, I hear someone express the idea that developers aren’t good at writing and that’s why they need technical writers. I want to be clear that it’s not true. I’ve known way too many developers who are good writers/good communicators to believe that.

Being a good developer and being a good communicator are not too mutually exclusive things. And you don’t need to have an English degree to make a meaningful contribution to the docs.

Don’t expect perfection of yourself

Any contribution you make to the docs will be appreciated. I promise.

Objects in motion stay in motion.

For this next piece of advice, I want to borrow from Newton’s first law of physics: objects in motion stay in motion.

The same is true for being productive too. Once you get started, it’s much easier to get going. The hardest part about being productive is getting started so it’s good to develop ways to trick yourself into getting started.

One of those tricks is the 5 minute rule, where you pick the task you want to work on, and you vow to work on it for five minutes, and five minutes only. Yes, you must stop after just five minutes.

You might ask: “What can I possibly get done in five minutes?” But you’d be surprised. Once you’ve gotten past that initial hurdle of getting started, it will be much easier to keep going.

Set micro goals

For any task you have to complete, break it down into the smallest possible units of progress and attack them one at a time.

Let’s say you need to write some docs about a new module you’ve created for Salt. Rather than approach that task as “Write that Salt module,” instead break down the very first steps you have to take and keep slicing them up into tiny, easily achievable micro-goals:

1. Open a Google Doc.
2. Name that Google Doc.
3. Write a single sentence. And so on.

Then celebrate completing each step along the way.

Pair docs work with something you enjoy

For example, you could only allow yourself a certain special snack when writing documentation or listen to a particular type of music.

Conclusion

In closing, I want to go back to the quotation that I referenced earlier in this presentation. There’s more to that quotation:

There’s common wisdom in the open source world: Everybody knows that the documentation is awful, that nobody wants to write it, and that this is just the way things are.

But the truth is that there are lots of people who want to write the docs. We just make it too hard for them to participate.

Rich goes on:

So, they write articles on Stack Overflow, on their blogs, and on third-party forums. Although this can be good, it’s also a great way for worst-practice solutions to bloom and gain momentum. Embracing these people and making them part of the official documentation effort for your project has many advantages.

That’s why at SaltStack, we’re taking steps to make it easier for you to participate in writing the docs by offering:

• Docs clinics
• Docs working groups
• And more doc jams like this in the future!

So, we hope you’ll join us in making our docs better and closing the docs value-action gap for the Salt docs today!