search

silverstripe / developer-docs

Developer documentation for Silverstripe CMS
Other
6 stars 57 forks source link

Include Available Version markers when documenting new features #500

Open Cheddam opened 2 months ago

Cheddam commented 2 months ago

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

maxime-rainville commented 2 months ago

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 commented 1 month ago

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 commented 1 month ago

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