GSoC 2023 Building jenkins.io with alternative tools project feedback solicitation

[Kris Stern]

RE: Seeking Community Input on Jenkins.io Tooling: Antora vs. Gatsby

Hi everyone,

We hope this email finds you well. We are reaching out to the Jenkins community to discuss the approach we should take to improve the tooling for jenkins.io moving forward as a part of the Google Summer of Code (GSoC) 2023 "Building jenkins.io with alternative tools" project. For more information regarding this project, please see https://www.jenkins.io/projects/gsoc/2023/projects/alternative-jenkinsio-build-tool/. We are considering two options as the alternative tools to Awestruct, which are Antora and Gatsby, and would greatly appreciate your engagement and feedback on this matter.

The proposed tooling enhancements aim to streamline the documentation management process, improve user experience, and enhance the overall functionality of jenkins.io. We have identified Antora and Gatsby as potential frameworks to achieve these goals. Before finalizing a decision of the exact tooling to be used, it is important to consider the pros and cons of each option for different parts of the website.

Antora, a documentation site generator, has gained popularity due to its simplicity and flexibility. It uses AsciiDoc as its primary markup language and supports modular documentation structures. Some advantages of Antora include:

• Easy integration with existing systems.
• Strong support for versioning and multi-repository setups.
• Highly customizable output formats.
• Extensive community support.
  

On the other hand, Gatsby, a modern static site generator, offers advanced performance optimizations and a wide range of plugins. It uses React.js as its underlying framework and offers benefits such as:

• Superior performance and optimized loading times.
• Extensive plugin ecosystem for customization and extensibility.
• Rich theming options for enhanced visual appeal.
• Active and growing developer community.

While both Antora and Gatsby have their strengths, we would like to express our preference for Antora for most of the parts based on our initial evaluation. However, we believe it is vital to gather insights and feedback from the community at large to ensure we will be making the best decision for the project as a whole. Your expertise and perspectives are invaluable in determining the most suitable tooling approach for jenkins.io.

To facilitate this discussion, please share your thoughts, concerns, and any relevant experiences with either Antora or Gatsby via this email thread. Your input will help us make an informed decision that aligns with the needs and expectations of the Jenkins community.

We greatly appreciate your time and contributions to the project. Thank you for being an integral part of the Jenkins community, and we look forward to receiving your invaluable feedback.

Best,

Kris Stern on behalf of Vandit Singh our GSoC contributor working on this project and the mentors' team

[Basil Crow]

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.

[Gavin Mogan]

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

--
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.

[Basil Crow]

On Fri, May 19, 2023 at 10:24 AM 'Gavin Mogan' via Jenkins Developers
<jenkin...@googlegroups.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.

I concur with Gavin. I have a strong preference for a more narrow project scope
that results in a complete migration in production rather than a more wide
project scope that fails to achieve a complete migration in production. The
reason for this strong preference is that for efforts that do not reach complete
migration in production, the value of the effort approaches zero as time
approaches infinity. A complete migration to production of even one component
achieves value immediately and is therefore preferable from my perspective.

> 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

[…]

> It also makes a clear migration plan. We can make docs/tutorials live when the
> content is fully pulled out. No half measures.

I concur with Gavin. I have a strong preference for factoring out the docs
content into a new Antora site and atomically cutting over the links from the
monolithic Awestruct site to the new Antora site, thus achieving complete
migration in production. The same process could be later followed for the blog.
What remains of the monolithic Awestruct site after the Antora and blog portions
have been factored out can then be dealt with on a case-by-case basis, but I
would rather not include this in the scope of GSoC. The reason for this is that
I fear it would introduce additional risk and delay progress on the Antora
portion of the effort, which is already significant in scope and risk in and of
itself.