Plugin Documentation-as-Code: Moving docs to GitHub

Published on 2019-10-21 by Oleg Nenashev

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:

GitHub Documentation example

Why?

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.

Examples

Since the announcement in September, more than 50 plugins were moved from Wiki to GitHub. Few examples:

Role Strategy example

How to enable GitHub documentation for your plugin?

  1. Convert documentation from Wiki to GitHub Asciidoc or Markdown format if you have not done it yet.

  2. Change the <url> field in pom.xml so that it points to GitHub (guide). Examples of valid links:

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

  4. Release the new plugin version

  5. Wait a few hours till the change propagates. After that, the Jenkins Plugin Site will show the new documentation from GitHub.

What’s next?

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.

How to contribute?

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.

Contributing to Documentation

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.

Migrating documentation:

If you have any questions about contributing to the documentation, please see this page or reach out to us in the Docs SIG Gitter chat.

Code contributions

Would you like to write some code in Java or JavaScript? Or would you like to work on CSS styles and improve Jenkins design? In such case you are welcome to contribute to the Jenkins Plugin Site. It is our own plugin marketplace implementation, and we invite contributions to this area. The plugin site is really easy to develop.

About the Author
Oleg Nenashev

Jenkins core maintainer and board member. Oleg started using Hudson for Hardware/Embedded projects in 2008 and became an active Jenkins contributor in 2012. Nowadays he leads several Jenkins SIGs, outreach programs (Google Summer of Code, Hacktoberfest) and Jenkins meetups in Switzerland and Russia. Oleg works for CloudBees and focuses on key projects in the community.