Doc'ing the Docs!

Apr 6, 2022

Since the docs are about to get a lot more eyes on them after the Astro Beta Lauch Week, I thought I’d take a moment to “doc the docs” for those who might want a window into our recent progress.

People have very kindly been referring to “the new docs” or “a re-writing of the docs” but, docs are always evolving… and at least in the case of a pre-v1 beta product, potentially outdated as soon as they’re published! It sometimes feels like they’ll never be caught up enough to qualify as “new.” But they are “actively maintained,” and sometimes, that’s the best you can hope for. 😅

Calling them “new” might also set up the expectation that we think we’re “done” and, nothing could be further from the truth! We’re just getting started…

With new users joining the Astro community, and current members upgrading from previous versions, it was important to us all that the docs get some love and a paint job to help everyone get off to a solid start.

Where We Started

As new features get added and others become deprecated, open source docs often (if you’re lucky!) get patched. Over time, one single page can lose its “single page-iness.” It can sound like it was written by a dozen different people in a dozen different places. (Spoiler alert: it probably was.)

It can end up being a confusing mix of general overview information too vague to be useful and highly-specific examples that solved one community member’s problem that one single time… whether or not they were even intended to work in the first place! (“Here we find the elusive “documented undocumented feature in its native habitat…”)

Things can end up added on a page because “other things like it are on this page” and not because that’s where a new or confused reader would go to find them. The scope of the page can creep, or content can end up duplicated (or even worse, not exactly duplicated) across multiple pages.

Step one for me with the Astro docs was to smooth out these rough edges.

Where We Are

We feel like we’ve mostly hit phase one of our goals: in addition to some technical reference docs now being auto-generated and updated, every page in the “Learn” sidebar has been read through and vetted for accuracy… typos, last-minute URL changes, and entirely brand new configurations as of last week aside. Oh, and by the way, Astro does SSR now?

Pages have been edited, and in some cases rearranged or combined with other pages so that each page clearly tells you about a thing. (And if we did it correctly, that thing is the page title!)

It doesn’t tell you everything about a thing. I can’t even guarantee it tells you most things about a thing. I know there are things about those things that you really want to know that it doesn’t (yet) tell you. But what it does tell you, it tells you pretty well.

I’d like to think that it probably tells you well enough about the thing that, if something’s not right there, you’ll know that it’s… just not in the docs! So, you hop into the Astro Discord and you ask about the thing there. Then, we make notes about what support questions get asked, to remind us of the things we haven’t yet put in the docs.

Support-Team-Docs!

Our eager team, with a full community of support behind us, has been working steadily for months to make the Astro docs a clean, reliable resource to get you started with Astro v1. We know it’s not perfect, and we do have plans for more, and more types of content going forward. It’s never going to be “done”… but that’s just the reality of supporting developers. And, that’s what docs are: support.

Astro is known for (notorious for??) its committment to community. We have long had a dedicated “Support Squad” whose members each receive individual notifications for every new support question posted in our Discord. Recently, we also added a “Team Docs” role that can similarly summon members with a mere mention. Both of these opt-in roles are open to any member of the community who feels like they don’t already get enough notifications.

We are all eager and enthusiastic to help you through any issues and get you back to building your site! And, we hope you’ll help us help you!

Go, You!

If you find a typo, a link to a page that we’ve moved, or the term renderer when it should be an integration now, you can let us know, or you can edit the page on GitHub yourself! One of the most rewarding aspects of working closely with the docs team this year has been seeing the number of small edits submitted by “first-time contributors.”

If you feel a topic hasn’t been covered in docs, or an example is confusing, come chat in our #docs channel, or file a GitHub Issue in the docs repository. (Maybe if you have the time, do a quick check to see if someone has already mentioned something similar, or whether there’s an active pull request related to your comment first… but do get involved!)

Launching into the Future

I’m excited for the future possibilities with our docs, and I’m personally hoping to get the chance to bring bit of my own teaching background and style into some dedicated walk-through guides and tutorials for onboarding new astronauts.

Astro, and the entire Astro community, is so user-friendly that we want our docs to be every bit as welcoming and supportive to developers of all experience levels. We know we can get you building with Astro, and we can’t wait to show you how!

Thanks for hanging in there as we made it to a v1 Docs beta, too. Stick around, and see where we go next! 🚀

Toggle Comments