Having been around for a number of the GSOC projects, and a number of the migration projects. I'm very worried about half finished state that nobody finishes. And honestly spent a lot of time cleaning up content on jenkins.io (some were .html, some were .md, some were .txt)
So to me, jenkins.io shouldn't be cut over to the new system, until the new system is fully populated. As basil mentioned, antoria is really good at what it does, and shouldn't be used for other things. The web components was effort to make uniform theming across all sites, instead of trying to merge everything into one site that tries to do a dozen different things. So my suggestion based on me trying to convert jenkins.io to gatsby a while ago and realizing its just too big 1) docs.jenkins.io (versioned, antora) 2) guides.jenkins.io (versioned, antora, but less likely to update?) 3) news.jenkins.io (out of scope of gsoc i think) aka blog. hook up a headless cms like netlifycms (all javascript + github), or maybe even strapi (really nice headless cms, we could have webhooks that update the repo) 4) Leave everything else on www.jenkins.io Antora has really nice alogila support, so we can have versioned docs. Gatsby does too, but its a little more custom. Docsearch is nice, but it requires scraping the site all the time, so the more we can make structured and uploaded the better. It also makes a clear migration plan. We can make docs/tutorials live when the content is fully pulled out. No half measures. I recently had to go look at version 2.x of the ember docs. I was able to pick my version, then search, and the whole thing remembered i was on 2.x and answered accordingly. see https://api.emberjs.com/ember/2.17/functions/@ember%2Fservice/inject On Thu, May 18, 2023 at 2:29 PM Basil Crow <m...@basilcrow.com> wrote: > The calculus of this decision seems different when it comes to the > documentation portions of the site (e.g., the end user documentation > and developer documentation) vs the regular content (e.g., the blog, > changelogs, and other static content). I think there may be a sweet > spot in using Antora for the end user documentation and developer > documentation while using another tool for the blog, changelogs, and > other static content. > > For the documentation portions of the site, Antora seems like a > perfect fit because it is specifically designed for documentation > sites and features first-class support for branching/versioning > documentation for multiple releases, combining multiple repositories > into a single site, etc. There has been a real need for versioned > documentation for multiple releases when working on e.g. Java Platform > support and other projects. I imagine the long-term maintenance cost > of Antora for the documentation portions of the site would be low: > just keeping the build running and keeping the templates up-to-date. > In contrast it seems that more effort would be required to use e.g. > Gatsby for a versioned/branched documentation site. Even with e.g. the > Rocketseat docs theme as a source of inspiration, it seems that Gatsby > offers less support for the versioned documentation use case > out-of-the-box and that custom code would need to be written and then > maintained in order to fully accommodate the versioned documentation > use case. > > In contrast, Antora was not designed for blogs, and Antora issue #444 > makes it clear that the maintainers do not intend to support blog-like > functionality in Antora. Using Antora for anything other than a > documentation site seems ill-advised, as this is not Antora's intended > use case. > > While it might be possible to use e.g. Gatsby for everything > (including the blog and documentation portions of the site), my sense > is that the benefits of using Antora for the documentation portions of > the site (both from an initial development and maintenance > perspective) may be more compelling. > > -- > You received this message because you are subscribed to the Google Groups > "Jenkins Developers" group. > To unsubscribe from this group and stop receiving emails from it, send an > email to jenkinsci-dev+unsubscr...@googlegroups.com. > To view this discussion on the web visit > https://groups.google.com/d/msgid/jenkinsci-dev/CAFwNDjqHDVdiwDTLiUAEtYF-3Pw4mb_Go9JDg2Ts%2B5LG%3DW7yPQ%40mail.gmail.com > . > > -- You received this message because you are subscribed to the Google Groups "Jenkins Developers" group. To unsubscribe from this group and stop receiving emails from it, send an email to jenkinsci-dev+unsubscr...@googlegroups.com. To view this discussion on the web visit https://groups.google.com/d/msgid/jenkinsci-dev/CAG%3D_DusMa-3WKNinkwRr2face3ZPxDzL%2BqWmn6KLU5_FfPr49w%40mail.gmail.com.
