Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Include Available Version markers when documenting new features #500

Open
1 task done
Cheddam opened this issue Apr 21, 2024 · 3 comments
Open
1 task done

Include Available Version markers when documenting new features #500

Cheddam opened this issue Apr 21, 2024 · 3 comments

Comments

@Cheddam
Copy link
Member

Cheddam commented Apr 21, 2024

Pages affected

Description

Often documentation for new features lands in this repo (and is published) before the version it becomes available in is shipped. Even after it ships, some projects may not be updated immediately. This can create some confusion when a developer discovers and attempts to reference documentation for a feature that isn't yet available in their project.

To combat this, I propose introducing a guideline to encourage the inclusion of an 'Available from x.y' flag above any newly created documentation. In addition, I'd suggest we prune these flags when branching a new major version of the docs, since all flagged documentation can be assumed to be current at that point.

Validations

  • Check that there isn't already an issue that reports the same problem
@maxime-rainville
Copy link
Contributor

This could be nice, but I'm also a bit concerned that it could add quite a bit of overhead when drafting doc.

If we did have a "this got release in 5.2" badge, we probably would need a process for removing those badges. Maybe when we tag a new major or when the minor where this shipped goes EOL.

Once upon a time, you could consult the doc specific minor release. This sot of did the same thing.

@GuySartorelli
Copy link
Member

If we did have a "this got release in 5.2" badge, we probably would need a process for removing those badges. Maybe when we tag a new major or when the minor where this shipped goes EOL.

I'd say just when we do a major. If the text for those 'badges' is the same across the board, we can just do a quick text search and remove them all at major time. So the CMS 6 docs won't talk about "only in cms 5.3" - but the CMS 5 docs still will, which is useful for people who are slow to upgrade.

I don't think it adds much overhead.

@GuySartorelli
Copy link
Member

GuySartorelli commented May 9, 2024

That said, it would also be very easy to update the docs site to have an option in the version dropdown for each minor release, if you want to do that instead.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

No branches or pull requests

3 participants