docs
docs copied to clipboard
withastro
Revisiting consistency in documenting features that were previously experimental
📚 Subject area/topic
Experimental Features
📋 Page(s) affected (or suggested, for new content)
-
View Transitions -
Sinceis current, but doesn't mention experimental. https://docs.astro.build/en/guides/view-transitions/ -
Astro Assets (
<Image />and<Picture />) - InconsistentSincehttps://docs.astro.build/en/guides/images/ - Content Collections - Inconsistent `Since https://docs.astro.build/en/guides/content-collections/
-
Prerender API (
export const prerender = true | false) - NoSincehttps://docs.astro.build/en/guides/server-side-rendering/#opting-in-to-pre-rendering-in-server-mode -
Dev Toolbar - No
Sincehttps://docs.astro.build/en/reference/configuration-reference/#dev-toolbar-options
📋 Description of content that is out-of-date or incorrect
Some features that have previously been added to Astro were first introduced as experimental.
In doing so, the addition of these features was documented as experimental when first introduced.
After the features were moved from experimental to officially supported, the documentation became inconsistent.
In the case of View Transitions, the transition:persist directive is documented to be introduced in [email protected]. However, at this time, this would have been experimental.
- Should this be documented as
[email protected], which was when the featured moved out ofexperimental?
In Astro Assets, the <Image /> component doesn't have a "since", while the <Picture /> tag is documented as [email protected]. Moreover, some documented properties of the Image component are flagged as experimental, added in 3.3.0.
- How should docs handle documenting when something is experimental and when it moves from experimental to official support?
Essentially, the documentation doesn't account for when something was experimental (if applicable). Those using older versions may believe that a feature is available when it was only experimental then.
🖥️ Reproduction in StackBlitz (if reporting incorrect content or code samples)
No response
These are all great observations @VoxelMC , and your gut reactions here have been spot on!
I would say that yes, we can update any "Since"'s to their official/non-experimental version numbers.
I would also say that anything missing a Since at all could have them added, yes!
I don't see anything on the images currently being marked as Experimental though? Can you point out specifically what you mean there.
Right now, the only things that are experimental are listed here: https://docs.astro.build/en/reference/configuration-reference/#experimental-flags and I don't think there is documentation outside of this page for any of those?
Just checking in on this issue @VoxelMC !
I'm confident saying that yes, anything that was at one point experimental but is no longer should have a Since/version that corresponds to when they were in the stable Astro core code (not introduced experimentally).
For future historians checking in on this issue, that's how we roll with our <Since /> component, and any updates to the docs to reflect that will be welcome!
(I don't immediately see what the problem is with the content collections nor images page from what you've linked, but the others do make sense to me, and updates to add/update the Since component are welcome!)
Just checking in on this issue @VoxelMC !
I'm confident saying that yes, anything that was at one point experimental but is no longer should have a Since/version that corresponds to when they were in the stable Astro core code (not introduced experimentally).
For future historians checking in on this issue, that's how we roll with our
<Since />component, and any updates to the docs to reflect that will be welcome!(I don't immediately see what the problem is with the content collections nor images page from what you've linked, but the others do make sense to me, and updates to add/update the Since component are welcome!)
Sounds good! I will propose some.changes the moment I have a chance to sit down and check if I haven't missed anything :)
As for experimental versions, will we be omitting those entirely?
I'm not sure what you mean about omitting experimental versions? Usually we do sequester anything experimental to either the config reference page for experimental flags, or in some cases an entire guide or API page devoted to the experimental feature. So, really where I expect this is even an issue is in a page (or config ref entry) that was experimental but is no longer so.
Can you give me an example of what falls under what you're asking so I can see what you mean?