Plugin Documentation-as-Code: Moving docs to GitHub
In September 2019 we announced support of GitHub as a source of documentation for the Jenkins Plugin Site. Thanks to Zbynek Konecny and Olivier Vernin and other contributors, now it is possible to store plugin documentation right inside plugin repositories instead of Jenkins Wiki which was historically difficult to maintain for plugin maintainers and for the Jenkins infrastructure team.
This blogpost may be interesting to plugin maintainers and to those who want to contribute to the Jenkins documentation. I will describe how to migrate plugin documentation to GitHub and to get pages like this one:
By using plugin GitHub repositories for documentation, plugin maintainers can follow the Documentation-as-code approach and make documentation changes a part of the pull requests so that documentation follow-ups do not get forgotten. It also gives an opportunity to review the documentation changes and to add documentation contributor recognition, especially if the story is combined with Release Drafter.
Unfortunately, before September 2019 usage of GitHub documentation was causing some issues. First of all, many plugin maintainers have already moved their documentation to GitHub, and it caused fragmentation of the documentation (Wiki, GitHub, jenkins.io). To address it, plugin maintainers still had to maintain stub Wiki pages with redirects, and users had to spend some time to find out where the real documentation is located. By supporting GitHub as a documentation source, we allow maintainers to phase out the plugin Wiki pages while improving the user experience.
And there are even more pressing reasons to do the migration now… If you are subscribed to the developer mailing list, you may have also seen an announcement by R. Tyler Croy about Jenkins Wiki stability issues and making it read-only as a temporary measure to stabilize the instance (mailing list thread). Although the functionality has been partially restored afterwards, there is a consensus in the Infrastructure team that we should gradually move to alternate solutions.
Convert documentation from Wiki to GitHub Asciidoc or Markdown format if you have not done it yet.
<url>field in pom.xml so that it points to GitHub (guide). Examples of valid links:
https://github.com/jenkinsci/mailer-plugin- plugin site will use GitHub REST API to extract README
https://github.com/jenkinsci/ssh-credentials-plugin/blob/master/doc/README.md- extraction of a plugin page from a custom location
Optional: Add badges to the page to improve look&feel and to provide quick links for users. There are standard badges for changelogs, chats, plugin site, and installation numbers.
Release the new plugin version
Wait a few hours till the change propagates. After that, the Jenkins Plugin Site will show the new documentation from GitHub.
The story is tracked as WEBSITE-406 which is a part of the wider subproject for using GitHub as a source of data for the Jenkins plugin site and update managers (WEBSITE-637). Later steps include support showing changelogs from GitHub releases, pulling plugin tags from GitHub, showing plugin logos, and using Repository Permission Updater as a source of the maintainer information.
October is a great time to contribute! Plugin documentation is one of the featured projects for Hacktoberfest, and we will welcome all contributions to the documentation and to the codebase.
We are looking for contributors who are interested to improve plugin documentation and to help us with migration from Wiki to GitHub. For dozens of plugins the documentation is already in GitHub, and you are welcome to submit pull requests against any repository.