Contributing to Jenkins Documentation

Contributed by Zainab Abubakar

Word Cloud of jenkins, open source and documentation words

Jenkins is the world’s leading open-source automation server used by companies large and small around the globe to implement continuous integration and continuous delivery.

I believe a product is only as good as its documentation. In this article, we are going to be looking at the structure of Jenkins documentation, its ongoing improvements, and contributing to Jenkins documentation.

Overview of Jenkins Documentation

Two layer pyramid showing Jenkins documentation overview. Top layer: Jenkins Documentation. Bottom layer: User Documentation, Developer Documentation, Solution Pages, Plugin Documentation

Jenkins has a lot of documentation divided into four major categories:

User documentation – Contains tutorials, user handbook, and references like Pipeline Syntax and Pipeline Steps to aid developers who want to use existing Jenkins functionalities and plugin features.
Developer documentation – Contains tutorials, developer reference and How-To Guides for developers who want to extend the existing functionalities of Jenkins by developing their plugins.
Solution pages – Explains using Jenkins with specific technologies (e.g. Java, PHP, or Docker) and also, implementation solutions like Pipeline.
Plugin documentation – Explains Jenkins plugin usages and is managed by plugin maintainers.

All of Jenkins’ documentation, excluding the plugin documentation, are managed by the Jenkins Special Interest Groups (SIG), who encourage, create, review documentation contributions, and improve the documentation with contributors and external communities from around the world. This group improves Jenkins use and adoption through its documentation.

Plugin documentation migration and update

A plugin is a software component that adds a specific feature to an existing computer program. When a program supports plug-ins, it enables customization and extension. Plugins can provide tremendously useful functionality for users, but it does them little good if there are no instructions on how to use these plugins properly.

As of the time of writing this article, Jenkins has over 1700 plugins providing numerous functionalities and support for different platforms. Jenkins’ plugin documentation is hosted on the Plugin Site. These pages are automatically generated using the metadata from the latest plugin release and an external documentation page. External documentation can be retrieved from GitHub or the Jenkins Wiki.

Screen shot of a sample Jenkins Documentation Page — *Sample Plugin documentation page*

Before September 2019, Jenkins had issues adopting GitHub as a source of plugin documentation. This was because some plugin maintainers had plugin documentation retrieved from GitHub and others retrieved from the wiki. This was confusing and made it difficult for users and contributors to navigate the documentation. Around September 2019, the Jenkins wiki started receiving a series of spam attacks and experiencing stability issues. This made the need to migrate to a different platform much clearer. , bringing GitHub to the forefront as the plugin documentation source. The Jenkins Wiki was converted to read-only and maintainers were now allowed to phase out Wiki pages after migrating to GitHub, thereby adopting the “documentation as code” approach. Plugin documentation is now stored inside plugin repositories instead of on the Jenkins Wiki, which was difficult to maintain.

Storing plugin documentation in the GitHub repository of the plugin allows maintainers to provide the same documentation from README pages and the Jenkins plugin site, and allows the use of Documentation-as-Code techniques, which means that all common practices can be applied:

Pull requests and reviews
Creating documentation in parallel with features
Editing docs from GitHub Web UI, with preview support
Versioning, documentation for previous plugin versions can be easily accessed

Conclusion

Jenkins community is actively working towards improving its documentation to create a better experience for Jenkins users and invites technical writers to join the community and contribute to the documentation being used by millions of Jenkins users worldwide.

If you are a newcomer, documentation is a great place to contribute. A lot of small patches can be done from the GitHub’s web interface even without forking repositories and cloning them locally.

You can get started on contributing to Jenkins documentation here. If you have further questions about Jenkins documentation or contributing to Jenkins, you can reach out in the Newcomer or Advocacy and Outreach SIG channels.

Interested? Why not contribute to Jenkins during Hacktoberfest!

Read Mark Waite’s post about the progress made in Jenkins documentation.