洪民憙 (Hong Minhee): @sarah11918 @ayo Wow! I had no idea Astro used this approach too. The concept of an API docs bash is brilliant! I completely agree that creating docs first helps validate the user experience early and dramatically improves development efficiency. Honestly, I didn't realize this was a more common practice. I'd love to hear more about your RFC process! Are there any blog posts or public resources about Astro's documentation workflow?

Sarah Rainsberger @sarah11918@mastodon.social

4/19/2025, 10:16:05 AM

Public

@ayo @hongminhee洪民憙 (Hong Minhee) It can be so helpful during design! Some people do it first-first. At Astro with our RFC process, minimal "docs" are updated as the feature is developed.

For Astro's new experimental Fonts API, we held not only an open API bash, but an API *docs* bash! After 2 hours looking at the draft docs ("Oh, it works like this? Oh, you expect people to do this? Oh, this is what it takes to explain how to use it?")... some design changes were implemented for sure, and everyone wins!

洪民憙 (Hong Minhee) @hongminhee@hackers.pub

4/19/2025, 10:29:07 AM

Public

@sarah11918Sarah Rainsberger @ayo Wow! I had no idea Astro used this approach too. The concept of an API docs bash is brilliant! I completely agree that creating docs first helps validate the user experience early and dramatically improves development efficiency. Honestly, I didn't realize this was a more common practice. I'd love to hear more about your RFC process! Are there any blog posts or public resources about Astro's documentation workflow?

If you have a fediverse account, you can reply to this note from your own instance. Search https://hackers.pub/ap/notes/01964d98-48c3-796d-a1f7-90fea801305f on your instance and reply to it.

Sarah Rainsberger @sarah11918@mastodon.social

4/19/2025, 10:52:13 AM

Public

@hongminhee洪民憙 (Hong Minhee) @ayo We have a roadmap repo for the RFC process: https://github.com/withastro/roadmap

We often have pretty good minimal user docs in the Stage 3/proposal, but even Stage 1 to just propose something encourages adding "end-goal" code examples of what it could look like if you're updating/changing/creating an API.

As for writing about our docs workflow, we've mostly focused on our community contributor process & guides like Astro Docs Docs (AD²) https://contribute.docs.astro.build , but a great idea!

GitHub - withastro/roadmap: Ideas, suggestions, and formal RFC proposals for the Astro project.

Ideas, suggestions, and formal RFC proposals for the Astro project. - withastro/roadmap

github.com · GitHub

Syntax	Description	Examples
`"` keyword `"`	Finds the string within quotes, including spaces. Case-insensitive. (Escape quotes inside with `\"`)	`"Hackers' Pub"`
`from:` handle	Finds content written by the specified user.	`from:hongminhee` `from:hongminhee@hollo.social`
`lang:` ISO 639-1	Finds content written in the specified language.	`lang:en`
`#` tag	Finds content with the specified tag. Case-insensitive.	`#HackersPub`
condition condition	Finds content that satisfies both conditions on either side of the space (logical AND).	`"Hackers' Pub" lang:en`
condition `OR` condition	Finds content that satisfies at least one of the conditions on either side of the OR operator (logical OR).	`#HackersPub OR "Hackers' Pub" lang:en`
`(` condition `)`	Combines the operators within the parentheses first.	`(#HackersPub OR "Hackers' Pub" OR "Hackers Pub") lang:en`