Project goal: Using alternative tooling (i.e., Antora) to build the Jenkins static site and provide documentation per Jenkins version
Skills to study/improve: Web development, AsciiDoc, Static website tooling, Proof of concept, Documentation
Jenkins.io is generated as a static website using Awestruct from AsciiDoc sources, YAML data files, and HAML templates stored in GitHub. One of the drawbacks of the current build method is that the technical documentation is not product version bound. It is thus not possible to view the documentation for a given Jenkins version. Only the latest can be viewed. This can lead to unnecessary confusion and is a worse experience than many other documentation sites like the git site, FreeBSD, and others..
The preferred tool to replace Awestruct is Antora.
The potential GSoC project would be to build a working site generator to demonstrate the existing site. Once the existing site is generated with Antora, the site should be extended to add version specific documentation.
The project has been discussed extensively at GitHub issue #5474, where some existing proof-of-concept code can be found referenced there.
There are multiple ways to approach the implementation, but from experimentation it has been found that the backend replacement requires minimal effort for the documentation, with the frontend implementation expected to require much effort to reproduce the look and feel of the current jenkins.io website. However, the blog can be split from the documentation using something like Gatsby, which is expected to make it easier for users to submit posts in the future.
While the tasks of the project are very clearly defined, the scope may vary depending on the plans of the contributor. If we split the project into milestones, we see three important ones that can be tackled in sequence: The most urgent milestone is (1) to set up the user documentation using Antora with versioning, while next would be (2) to set up the developer documentation with Antora without versioning, and finally (3) to set up the blog using Gatsby. The contributor can choose either 1, or a combination of 1 + 2, or a combination of 1 + 2 + 3, but not in any other way. The expected project outcome is at least a drop-in replacement website that is building locally.
The outcome of this project is expected to produce visible impact they can showcase in their portfolio of the jenkins.io website, as the GSoC contributor is also expected to contribute via UI/UX improvements beyond the basic tooling required.
Please note that for the UI/UX improvement portion we may need to deal with the jenkins-io-components repo, where the code for components shared by various Jenkins websites (jenkins.io, plugins.jenkins.io, etc.) is currently hosted.
Documentation quick start steps include:
Build the current documentation site locally
Become familiar with the current site, including:
Page types and how they are generated
Version specific content in tutorials (like "Improve a plugin")
Page content sources
HAML / Ruby
Syntax and spelling checks
Fix several "good first issues"
Explore jenkins-io-components repo
Review version specific documentation techniques (some of them are Antora sites)
Python (sphinx is the generator)
Static website tooling
YAML data files
Proof of concept
The deliverables of the project(s) would be:
Iterative and incremental improvements to the site throughout the project
A fully automated (CI ready) build procedure, equivalent to the existing one, but using Antora
Demonstration that all the existing pages are rendered in an equivalent way
Suggestions of improved page design(s)
A list of all automation that are difficult/impossible to port to the new tool
Suggestions and demos of alternative ways to solve this
Demonstration of the versioned documentation automated tooling
Description of the publication process (how does one contribute to document a new or modified feature)
Basically any good-first-issue listed in the jenkins.io GitHub repo would do. These can be accessed at the GitHub repo issues tracker with the "good first issue" label.