Tip 49 - NWTWWHB

Aug 11, 2024

”Is it good?"

"Well, it’s not worse than what we had before…"

"Ship it!”

Not every submission we receive to Astro does is… amazing. If we’re lucky, they’re helpful.

We’re not always lucky.

But, we understand that someone believed this was a valuable contribution. They willingly and voluntarily took the time to fork the repo, edit the content, create a pull request… they must really want to help!

Maintaining community-driven docs means identifying and channelling the desire to contribute. Community is the lifeblood of an open-source project. It’s who we write the docs for and the reason we exist.

We invest in our community by providing public-facing docs, and we can allow them to feel invested in us by including them in our project. Spot a typo? Fix it! Did an external link change? Update it! Want to rewrite the section on passing props to framework components? Uh… maybe let’s talk?

When I can’t immediately see how a proposed change is useful, I try to “Yes, and…” I ask what they hoped to achieve. What problem were they trying to solve, and can I help explore the problem with then to see if we can find a solution that fits within Astro docs’ scope, mandate, and style?

✅ Finding a way to say yes to things!

There are myriad reasons why someone may choose to contribute. A problematic contribution is an opportunity to engage, and to figure out whether their very real issue can lead to an outcome that validates their experience and addresses their desire to be a part of the solution… without messing up your lovely docs in the process!

A standard of “not worse than what we had before” (#NWTWWHB) is inclusive. And, I am including my own half-baked ideas, too! We may not accept every submission that comes our way. But we also don’t waste as much time deciding, and our process actively discourages gate keeping or making potential contributors jump through excessive hoops.

Did you not make things worse? Congratulations! That’s all any of us can hope for at the end of the day. Welcome to Team Docs! Here’s your badge, find a spot in our FacePile…

You can have an active culture of accepting community contributions and still maintain docs quality. In fact, you have no choice! Too many people are watching now… 😅

See the whole list of tips!

Toggle Comments