Thank you for sharing your concerns and providing your valuable insights based on your experience with GSOC projects and migration efforts. I understand your worry about the half-finished state that often occurs when transitioning to new systems, as well as the challenges you faced while cleaning up content on jenkins.io. It is crucial to ensure a smooth and complete transition to avoid any inconsistencies or unfinished work.
Taking into account your suggestions, it seems reasonable to hold off on migrating jenkins.io to the new system until it is fully populated. This approach ensures that the new system is ready to handle all the content and functionality currently present on jenkins.io before making the switch. I agree that Antora is excellent at what it does and should be used for its intended purpose, which is documentation. However we won't create blogs with Antora it would be done with Gatsby which was the preferred tool as submitting blogposts would be easy with it. - Gatsby for Blogs, Roadmaps, Changelogs and Security Advisories(All the .YAML stuff) - Antora for Rest of the site On Friday, May 19, 2023 at 10:54:09 PM UTC+5:30 ga...@gavinmogan.com wrote: > 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-de...@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/dddda0e9-eb0a-40ad-b743-4db59ad36e88n%40googlegroups.com.
