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.

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

[Vandit Singh]

Thank you for sharing your thoughts and insights regarding the decision-making process for our website's documentation. I appreciate your careful consideration of the different aspects involved.

Based on your analysis, it seems that Antora would be an ideal choice for the end user documentation and developer documentation sections of our site.

You also mentioned that Antora's long-term maintenance cost for the documentation portions of the site would be relatively low, primarily focusing on keeping the build running and updating the templates. Comparatively, using a tool like Gatsby for versioned/branched documentation might require more effort and custom code to fully accommodate our needs. Therefore, considering the initial development and maintenance perspectives, the benefits of employing Antora for documentation appear to be quite compelling.

However, I understand that Antora was not designed for blog-like functionality, as indicated in Antora issue #444 and the intentions of its maintainers. Given this limitation, it would be prudent to explore alternative solutions for our blog, changelogs, and other static content. Antora does not use .yml files as content sources, which poses a challenge for incorporating these specific elements into an Antora-based setup.

One option could be to consider using another tool, such as Gatsby, for the blog, changelogs, and static content. Gatsby provides more out-of-the-box support for the versioned documentation use case and offers greater flexibility for customizing and maintaining these aspects of our site. By adopting this approach, we can leverage the strengths of Antora for our documentation while utilizing a tool better suited for handling the blog and static content requirements.

In summary, I propose that we use Antora for the entire site, except for the blogs, changelogs, and security advisories and all the content written in .yml format. Antora's intended use case does not align with handling this type of content, but we can explore other solutions like Gatsby to cater to these specific needs.

Please let me know your thoughts on this proposed approach, and if you have any alternative suggestions. I value your expertise and look forward to further discussions on this matter.

Thank you once again for your comprehensive analysis and contribution to this decision-making process.

Best regards,
Vandit Singh

[Vandit Singh]

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 

[Mark Waite]

On Friday, May 19, 2023 at 11:24:09 AM UTC-6 Gavin 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)

I really like the idea of a new top level URL, docs.jenkins.io, for the versioned documentation and I really like the idea that it as the first goal of the project.

The new top level URL can leave the existing content undisturbed until docs.jenkins.io is ready to receive some redirects.

Mark Waite

 

[Kris Stern]

Hi Basil and Gavin,

Thanks for the feedback and suggestions! We do agree with Gavin's approach that we should have the following as end goals of this GSoC project:

1) "docs.jenkins.io" (versioned, with Antora) - our first and foremost priority

2) "guides.jenkins.io" (versioned, with Antora, but less likely to update) - our next priority, or can be subsumed under "docs.jenkins.io".

3) "news.jenkins.io" a.k.a. the blog with Gatsby. hook up a headless CMS like Strapi (which we could have webhooks to update the repo). 

4) Leave everything else on www.jenkins.io or redo everything else with Gatsby. 

@mark.ea...@gmail.com I agree it would be a good idea for @Vandit Singh to strive toward a completed versioned docs section under the subdomain "docs.jenkins.io" as the minimum success metric for the GSoC project this summer. But if Vandit is feeling ambitious, as discussed internally previously we could extend his GSoC project so that more work can be completed. 

Also Gavin, we may need your help in setting up the new subdomains required to host the alternatively built site contents. For this I will approach you for assistance later. 

Best,

Kris on behalf of the project mentors' team

---

From: jenkin...@googlegroups.com <jenkin...@googlegroups.com> on behalf of Mark Waite <mark.ea...@gmail.com>
Sent: 23 May 2023 02:29
To: Jenkins Developers <jenkin...@googlegroups.com>
Subject: Re: GSoC 2023 Building jenkins.io with alternative tools project feedback solicitation

 

--

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/a1193a15-9fc1-4ba0-841b-d8bc088067ben%40googlegroups.com.