Astro's Community-Driven Docs

Nov 4, 2022

This was orignally written in early June 2022, in response to the question, “Have you written anything about your community-driven approach to Docs at Astro?” My first response was, “Give me a few days.” My second response was this.

Community-Driven

To us, community-driven means:

collaborative - docs are reviewed, discussed and approved publicly on GitHub
responsive - docs are written not just abstractly keeping the reader in mind, but often directly in response to stated or observed needs from the community
participatory - docs are open to contributions (of any type) from any member of the community

PR Process

What makes us slow, makes us grow!

Inspired by the collaborative nature of the Astro core project itself, no PR passes without an LGTM from at least one (other) Team Docs member.

(Fun fact: since we are open to contributions from community members of all experience levels, many who contribute to our docs were unfamiliar with what LGTM stood for. Some ventured tentative guesses, many of which were way more fun than “Looks Good To Me.” After exploring various alternatives, our current favourite is, “Let’s Get That Money!”)

Does it make it slower that we as maintainers don’t even merge our own PRs with a simple typo fix?

Yeah. But, we accept this tradeoff. It’s a simple way to ensure that an author didn’t inadvertently introduce a new typo to be fixed. But also, it means that:

We encourage looking at the PRs regularly so that everyone can be kept up to date with what is happening, to the extent that they want.
We can easily receive contributions from any community member in the form of an LGTM, even if they are not willing or able to write content or do more time-consuming tasks such as reviewing an entire page or testing code examples.
We naturally put built-in onboarding and guard rails in place to be able to manage these contributions from such a wide range of contributors, and to be able to direct them to small PR contributions first.
We demonstrate everything that goes into a docs site, down to typo fixes, and model a diverse range of contributions for those wanting to get involved.
We set realistic expectations of the process of “getting merged,” and that not every idea immediately makes it into production. And, it gives explicit permission to think about the PR carefully, as well as to wait for other perspectives, or second-thoughts, to surface.
We provide an open opportunity for public proof of open source involvment, and our contributors can claim and own this experience.

Support as Docs

Long before there was a “Team Docs,” Astro had an active “Support Squad” role on Discord. Our approach to support has become the stuff of legends, and some people have chosen to use Astro, still in alpha itself until recently, on the basis of our community alone.

When “Team Docs” was established, many of our inaugural members were also seasoned Squaddies. We knew the questions people were asking in our support threads, and we had lots of practice answering them. It was natural for us to apply that experience to the docs.

If someone asks a question, answer with documentation. If the documentation doesn’t exist, write the documentation, then answer the question with documentation. Jen Luker https://twitter.com/knitcodemonkey/status/1486214423190519811

As a “newer” project with very few answers written on blogs or Stack Overflow, we knew that the only public place people were able to find answers was in our Discord channel. Team Docs had the advantage of knowing exactly what our users were asking. We could use this to steer our documentation decisions, to add or update content, and to prioritize.

We created crudely-categorized, monthly tallys of the general topics our users were asking about to point us to areas of existing documentation that could be improved. We also had a supply of raw content already written, and unsuspecting future docs contributors to get us started!

One regular task we have now incorporated into Team Docs is to go through support threads and be a little bolder about asking, “What could we have put in the docs that would have helped you out with this?” or “Where in the docs would you have expected to find this?” and to even suggest that thread participants (question askers and answerers alike) are welcome to make issues and PRs to the docs repo… partly to save us from recreating what’s already in the thread, but also to encourage and onboard new contributors.

(Re)Writing in Public

Since we were the only game in town, our docs were not only our single source of truth; they were the single source of truth.

Although we knew our docs needed restructuring, they also needed to keep up with constantly evolving features that come with early version product changes. We didn’t feel that we could split our resources writing a second “idealized” set of docs from scratch behind the scenes while at the same time maintaining the only docs that existed for our community. They needed to work now

We decided to edit existing content in place, guided by two key questions inspired by our Support Squad background:

Is this content correct?
Is this content helpful?

Maybe our existing explanation on how page routing works in Astro was a little underwhelming. But if it was correct and if it gave the reader some immediate help to get them going or unstuck, it was serving its purpose until we could prioritize rewriting.

“How can I help, if I have some time today?”

Now that we have a full-fledged Team Docs, I attempt to “wrangle” their efforts and energies by explicitly demonstrating how any member of the community can contribute.

Regularly, I post messages in our Astro Discord #docs that answer what I (tongue-in-cheekly) assume to be everyone’s burning question, “How can I help, if I have some time today?”

These answers might include anything (because, docs really does require a bit of everything) as I attempt to push the boundaries of how we think of “docs,” and who is a “docs person.”

These “answers” are concrete, pointed tasks that I validate by explicitly asking for them.

Lots of people want to “help” but might feel overwhelmed about where to start, or unsure whether their contribution will be useful. They might not have a lot of time or energy, and might not realize just how valuable the smallest contribution can be, especially when my own typo fix might still sitting in a PR!

Just some of the tasks I’ve highlighted include:

reviewing particular PRs with a quick description of what it involves
writing new content, in response to an existing issue
testing a particular code sample or set of instructions
fixes to the site or styling improvements
researching something that needs to be written
translating a particular word or phrase, if not an entire page
brainstorming a list of “common error messages” for our new Troubleshooting page
labeling issues and PRs, even if you don’t do anything with/about them

… all the way down to simply stating a preference between two link colours! No contribution is too small!

And then when people do step up, we celebrate their efforts. We have added a “FacePile” to our main docs landing page showing the GitHub avatars of every contributor to the docs repo. We regularly show off our docs progress in our Discord Showcase channel, because our docs site is a showcase of our community members’ efforts!

Aspirations

I do have some specific goals moving forward, and I hope that by building a solid community foundation around our docs site, we will be in a sustainable position to achieve them. It is easier for me, as docs lead, to step back and let the system chug along if I know that our regular docs maintenance process is well-established, and works even without me on the critical path.

I have even seen one of our lead translators from our i18n group start addressing their crew with their own delightful, “How can I help?” posts in the Discord. We aim to provide our community docs members with clear, consistent messages so they can feel confident contributing to the docs. Modeling these tasks, routines, and ceremonies publicly also means that budding community leaders can feel confident stepping into leadership roles.

This early investment in community-driven docs now frees me up to spend some focused time writing our first introductory tutorial from scratch, which is as good an ulterior motive as it gets. My background in education and curriculum writing, and my current involvement in projects like #DevEdBookClub on Twitter can bring some relevant theory and practice not only to the tasks of planning, prioritizing, and steering the efforts of our contributors, but also to creating some fresh content influenced by common industry models and practices.

I am also working to formalize our communication channels between Support Squad and Team Docs, with written contributor guides for each role so they know how they can be supporting each other in their interconnected efforts.

We also want to give our docs a thorough “Every Page is Page One” treatment. I have started to emphasize to Team Docs that, no matter how much of a page turner it might be, few people will read our docs site like a book, cover to cover. Furthermore, you can’t be guaranteed that they will arrive to the docs site on the landing page. All pages have to be welcoming to new arrivals. Now that our content is correct and helpful, it needs to also be discoverable and navigable.

Docs are never done

The docs are never done is a true, and also potentially overwhelming statement. It can be all the more overwhelming, and intimidating, when this all plays out publicly, in real-time. As we are trying to systematically improve the site as a whole with a unified approach, we are also constantly responding to internal demands and external feedback.

We have opted for a community approach to our docs that does its best to work with and for our community: to encourage contributions from people who might never have thought of themselves as contributors, and to provide a structure that allows them to feel comfortable, and even celebrated, while doing so.

Astro has attracted and kept users despite its still-beta status because of its strong commitment to cultivating a vibrant, healthy community. Happy people overlook a surprising number of bugs, missteps and limitations, especially when they can see that someone is working to address them.

We bring that same community vibe to our docs, and provide an easy way for anyone to jump in themselves, and become that someone who is working to address them!