Skip to content

Doc'ing the Docs!

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

Ā© 2021 - 2024 Sarah Rainsberger. Except where otherwise noted, and/or quoting external sources, the content of this site is licensed under CC BY-NC-SA 4.0