docs
docs copied to clipboard
contao
Freed docs from dead wood
The docs have accumulated a lot of old stuff which we need to cleanup now that 4.4 is not supported anymore. Otherwise the docs become unreadable. I have invested a good 1.5 hours for this already but I'm sure there might be more to clean up 😊
I don't know if I like this. There are probably still a lot of 4.4 installations out there. Could we move this parts somewhere instead of delete?
4.4 is EOL, there's absolutely no point in keeping our docs cluttered with version hints. I don't think people can expect us to maintain documentation of old versions. Otherwise, where are the docs for Contao 3?
there's absolutely no point in keeping our docs cluttered with version hints
In principle, I also feel this way. At least for the manual, especially since the forum always points out the use of current versions. There will also always be added new version hints. If we do not change anything, it will certainly become unwieldy.
One could at least consider to remove all existing previous versions hints with Contao 5 (or any major releases) and from then on e.g. define (and communicate) a time cycle (similar to the release phases) from which existing versions hints will be removed again for the purpose of overview.
What about creating a branch/version for 4.4 with the current docs version that will not be touched/updated/maintained anymore and use 4.9 as base for the current/main branch? So current information for 4.4 will be accessible but we don't need to take care of 4.4 in new documentation updates.
We decided early on not to use multiple branches for multiple Contao versions. And not maintaining something that is publicly deployed is not an option.
Symfony is doing it also in it's docs. I thought there are not multiple branches cause off the additional maintenance work, but have a stale branch would not be additional maintenance work. From my point of view this would be a very good compromise for keeping old docs and keep current docs clean.
but have a stale branch would not be additional maintenance work
There is no need for a branch then, you would just need to publish the current version (369501ed22eb5deea322e90658e8340861fa314b) somewhere. But publishing it means that Google will find it and people would potentially end up in the wrong documentation. This is not an easy desicion IMO.
How it is technically solved (branch or static placed somewhere) could be discussed later :) I would prefer have a version switch like in nearly any other documentation with currently two option: "4.4-4.8 (unmaintained)" and "4.9+ (current)". And at the top of the 4.4-docs we can place an "unmaintained" notice as symfony is doing it. If we do it that way, we have the legacy docs without additional maintenance work and could drop the legacy information in the docs without losing the informations forever AND have less maintenance work for the current docs :)
I also like version switcher in the docs, like the one Symfony has. Reading docs with version hints is more effort, because you're always keeping mental notes and "build" the result in your head when you reach the bottom of the page.
