Skip to content
Astro Docs Docs (AD²)

How we write docs

Community-Driven

To us, community-driven means:

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

You are welcome, and you are a part of the team.

Maintainer-Led

We have an offical team of Astro Docs Maintainers and a Docs Lead who is ulimately responsible for leading and managing the entire project.

The Docs Lead:

  • works closely with developers building the core Astro codebase to oversee the documentation of new Astro features released
  • manages and supports the maintainers who participate in the docs repository
  • oversees the reviewing of community contributions, including translations
  • maintains the site’s information architecture, restructuring and refreshing all aspects of content and its organization as necessary
  • regularly audits content as features grow and change, requiring new or updated content
  • provides leadership and a consistent voice for the entire project

Astro docs relies on its community for contributions, but not every contribution supports the team’s plans or fills an important need for the project.

If you are new to contributing to Astro, please take a moment to read the section for first-time contributors, especially about what are helpful first-time contributions to make. Here, you will learn about how our project works and how you can help!

Docs-as-code

Our documentation site is an Astro site! When you contribute to Astro Docs, you are also contributing to the codebase of an Astro project. This means that all contributions — code, content, design, translations — use the same git-based, pull request (PR) system. Our docs writers are or become just as familiar with GitHub and PR reviews as Astro coders. No matter which kind of contribution you make, everyone goes through the same system and has the same experience. This means that docs contributors also already know how to make contributions to Astro’s core codebase, too!

LGTM

As part of our collaborative process, no pull request passes without an LGTM (Looks good to me! Let’s get that money!) from at least one other Team Docs member. Even core members must wait for an approval before merging.

Some of the benefits we get from this system include:

  • PRs stay around longer so that everyone can be kept up to date with what is happening, to the extent that they want.
  • Anyone can contribute, meaningfully, just by typing LGTM. No need to write content or do more time-consuming tasks such as reviewing an entire page or testing code examples. Proofread or evaluate an existing contribution to help us get through them all!
  • We demonstrate that anyone can make mistakes, or have a bad idea, even core members! We value different perspectives and opinions, and having more people involved helps us make better decisions and catch both typos and brain-os.
  • We set realistic expectations of the (sometimes lengthy) process of “getting merged” and make it clear that not every idea immediately (or ever!) makes it into production.
  • With no expectation of immediate reviews or quick merges, we give ourselves us explicit permission to think about the PR carefully, as well as to wait for other perspectives, or second-thoughts, to surface.
  • Every PR receives feedback, for better or worse. We as maintainers can publicly communicate our expectations and decisions so that both current and future contributors can learn from this feedback.

Types of Contributions

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.

Some of the helpful contributions we regularly receive include:

  • reviewing existing PRs
  • 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 and participating in discussions
  • labeling or triaging 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!