Hi David & Cameleers, On Tue, Feb 8, 2022 at 7:57 PM David Jencks <david.a.jen...@gmail.com> wrote: > We have a problem in a lot of blog posts that they link into the Antora > generated docs.
Yes this happens with increasing frequency and it is problematic > Many link to the “next” version of the docs which has two problems: > > - as release announcements, they should link to the doc version that’s been > released. > - there’s no reason to suppose any particular page in ‘next’ is going to stay > there. We should agree never to link to `next` or `latest`, but to concrete versions. A validation rule to that effect can be implemented to enforce this. > From this point of view we should change all the release announcement links > to point to the docs in the released version. That’s an improvement, but it > will cause another problem: > > - At the moment our plan is to drop the docs for no-longer-supported versions > when they aren’t used by supported versions of other subprojects. > > So, eventually all the links to docs in blog posts will break. > > I think we should: > > - change all blog post links to point to explicit appropriate doc versions. > I’m somewhat afraid about how big a job this will be, but the current links > to “next” are clearly wrong in all cases. > > - Decide what to do about old versions. I can think of three possibilities: > > — Keep all the old docs versions in the docs, perhaps marking them > “unsupported”. There might be ways to do this without building those > portions of the website every time but this would take some time and thought > and wouldn’t be my highest priority for some time. > — Delink broken links in the blog, marking them something “no longer > documented” or “obsolete” or something. > — Remove the blog posts about no-longer-documented versions. > > I really don’t know what to do here, so I’m hoping discussion will result in > a “best path forward”. I'd like to be in a place where we could keep the old versions of the documentation, given that we've split off the website source and publish repositories. Perhaps there is a way forward by keeping more content in the publish repositories, even if it is not built/linked from the site. As a form of archived documentation. For that we would need to keep everything within the "/_" (CSS, images...) and when publishing instead of deleting everything[1] we delete only the built versions. The drawback of this approach is that it might overwhelm whatever is done outside of our purview to publish the site, but we can try and see if it really does and engage INFRA to explore options. zoran [1] https://github.com/apache/camel-website/blob/b978a3e6af3fcc97808515bc01a004ddd28426a6/Jenkinsfile#L99 -- Zoran Regvart
