Contributed by Mark Waite
Jenkins Documentation Progress
The Jenkins project joined the Continuous Delivery Foundation in 2019 as one of the first open-source projects to be part of the foundation. Since then, we’ve made great progress in Jenkins documentation and have seen benefits from our CDF membership.
Documentation Development Statistics
The Continuous Delivery Foundation provides a metrics site that monitors the source code repositories of the Jenkins project. The Documentation Special Interest Group (SIG) monitors a small subset of those statistics for the Jenkins documentation repository. The statistics provide useful insights into areas where we’re improving and other areas where we still need to improve.
Improved – PR time to engagement
Jenkins documentation changes are proposed by community authors through pull requests to the jenkins.io GitHub repository. We’ve managed our documentation as code in that GitHub repository for many years. The last 6 months of data show a noticeable improvement in time between the initial proposal of a pull request and a response to the pull request. (Click the image for a link to the current data.)
Time to respond has become more consistent, even as the number of contributors has increased.
Needs Improvement – Time from PR open to merge
The last 12 months of data have shown much better consistency in merging pull requests. Most pull requests merge in less than 24 hours and 85% of pull requests merge in less than 4 days. The Jenkins documentation has benefited from new contributors from the Jenkins user experience Hackfest and from the Google Season of Docs project. We’ve expanded the copy editors team and are very grateful for the reviews that those contributors are providing (Click the image for a link to the current data.)
The graph highlights that documentation pull requests are being merged more consistently. It also shows a trend to longer times from open to merge in the last two months. We hope to reverse that trend over the coming months.
Wiki Migration for Plugins
Jenkins plugin documentation had been maintained in the Jenkins Wiki for many years. The “distance” between the Jenkins documentation on the wiki and the plugin source code on GitHub often made it difficult to understand what had changed from one release to the next, and which new features were introduced in a plugin release.
In September 2019 we announced support for plugin documentation stored inside the GitHub repositories. We now have blog posts, documentation, webinars, conversion tools, and progress measurements (and here) to assist plugin maintainers and other contributors as they migrate documentation from the Jenkins wiki to the plugin GitHub repositories.
The first month we transitioned 50 plugins from wiki to GitHub repository documentation. We now have over 500 plugins converted or in the conversion process. Special thanks to Gavin Mogan for the conversion tool, the conversion tracking site, and the extensions for the Jenkins plugins site. We’d love to have more pull requests helping the transition of plugins from Wiki documentation to documentation in their GitHub repository.
Wiki Migration for Jenkins Documentation
The documentation for Jenkins core was initially developed and maintained on the Jenkins wiki. That was a powerful way to allow contributors to rapidly share their experiences and ask questions. Unfortunately, the unstructured nature of wiki documentation meant that there was not an overarching structure to the documentation.
The jenkins.io site was launched as part of Jenkins 2.0. It is a static site generated from ASCIIDOC markup maintained in a git repository. The site provides more structure and better organization than the Jenkins wiki. However, because it is a newer site, it contains less content than the content assembled in the Jenkins wiki over more than 10 years of development.
In late 2019, comments and “wiki spam” became such a problem on the Jenkins wiki that we had to make the Jenkins wiki “read-only”. That change has motivated the Jenkins project to greater efforts migrating Jenkins core documentation from the wiki to jenkins.io.
The May 2020 Jenkins User Experience Hackfest converted more than 40 pages from wiki to the jenkins.io site and added significant improvements to the quality and the quantity of documentation on jenkins.io.
Jenkins Plugins Site
The Jenkins plugins site is the primary entry point for users and administrators as they search for a plugin to meet their needs. The plugins site provides the documentation, release history, dependencies, and list of known issues for over 1000 Jenkins plugins.
The plugins site was created as part of the Jenkins 2.0 initiatives. It would display plugin documentation that it had dynamically extracted from the Jenkins wiki. The dynamic extraction was good to get the latest documentation and avoided duplication of the documentation into a separate site, but it was slow to respond to users and slow to search.
Gavin Mogan converted the Jenkins plugins site from a dynamic site to a static site. The static site provides much faster response times for users and reduces the load on the plugins site server and the Jenkins wiki server.
Gavin has recently extended the Jenkins plugins site to show the changelogs for GitHub plugin releases. The changelog makes it much easier for Jenkins administrators to understand the changes in plugin releases as they consider using a plugin or updating to a new plugin release.
Gavin has also included the list of known issues for each plugin in the plugins site. Administrators can review the summary text for plugin issues and can navigate to those issues with a single click.
What’s Next
The Jenkins roadmap includes plans for documentation improvements in many different areas.
Improvements are being addressed in the Documentation special interest group, the Pipeline Authoring special interest group, and through the efforts of the Advocacy and Outreach special interest group and the Google Season of Docs program inside the Jenkins project.
How to Help
The Jenkins project welcomes documentation contributions. Help is welcomed in many different areas, including:
- Jenkins core documentation good first issues
- Jenkins core documentation GitHub issues and Jira issues
- Jenkins core documentation wiki migration
- Jenkins core documentation pull request review
- Jenkins plugin documentation wiki migration
- Jenkins plugin documentation Jira issues
Instructions for core documentation contributions are available in the contributing guide. Instructions for plugin documentation and the documentation conversion process are included in the plugin developers guide to documentation.
In addition to those general purpose areas, we also have specific areas of documentation effort coming soon:
- Complete the update to agent terminology
- Replace inappropriate and offensive terminology
We’re delighted to have help in our documentation and look forward to contributions.
