Imagine getting invited to a friend-of-a-friend's house and then when you get there, there's no indication of where to go. Do you knock? Go through the house? Around back? Do you need to 'beware of dog'? Oh CRUD, did you forget to bring dessert?!

Would you feel... awkward? Frustrated? Annoyed? Anxious?

As I help integrate some open source starters for my client, we are updating the docs accordingly but something was missing...! 👀

There were no instructions on how to get up and running locally with the docs.

There were some details about the way the docs were parsed and generated but nothing about how a first-time contributor could quickly get crackin' on code.

Yet... product engineers were working on the docs daily, and there had been external contributors in the past.

So... it must be dead simple, then? 🤔

While testing the contributor onboarding process, I ran into several issues (missing tools and frameworks) and had to dig in the code to figure out I needed to set up a local database (in Docker, no less). I also noticed there were special custom building blocks being parsed in Markdown that weren't documented. There wasn't guidance on where exactly to place new files or how to rebuild the docs so they actually displayed when running the site.

Not so simple, it turns out. The onboarding turned out to require about 6 steps + 8 "clarifying notes" that depended on different local machine configurations. This is part of an audit I do, so in response, we made sure to update the README for future first-time contributors.

Even if you think your docs are simple to contribute to, they probably aren't, so make sure to explain how a first-time contributor can get up and running. In fact, it's super common to miss alternative platform issues (especially for product engineers used to working on a single platform).

You can go a step further and build this into the process of onboarding new engineers to your team. It's a great way to get people's feet wet and it was part of our onboarding process for my old team to have folks make a contribution to our monorepo and update any stale contributor documentation as part of that.

Here's the rub...

It's hard enough to be a first-time contributor to a complex project; you don't need to make the experience even worse by making the docs hard to contribute to too.

Please don't make me think about how to get to your backyard docs BBQ.

Have a lovely day,
Kamran