Jenkins User Experience Hackfest Documentation Results
Documentation is not glamorous, but it is goodness.
Jenkins technical documentation is an important part of our project as it is key to using Jenkins well. Good documentation guides users and encourages good implementation choices. It is a crucial part of the user experience.
In the recent Jenkins UI/UX hackfest, documentation was a specific track to improve the Jenkins user experience. We received many improvements from experienced Jenkins contributors and newcomers alike. Contributors from all around the world submitted pull requests for documentation on installing, managing, administering, and operating Jenkins.
Documentation migration from Wiki
The Jenkins Wiki pages have collected 15 years of experience and wisdom for Jenkins users. However, that experience and wisdom is intermixed with inaccurate, incomplete, and outdated information.
The Jenkins Wiki migration project identified the 50 most accessed pages on the Jenkins wiki and created GitHub issues to track the migration of those pages to www.jenkins.io. This was our first large scale experiment using GitHub issues for documentation. The results have been overwhelmingly positive. Hackfest contributors added new sections to many documentation chapters, including:
The Hackfest closed 19 of the wiki migration issues. Work is in progress on an additional 25 wiki migration issues. We’ve made great progress and look forward to even better results in the future. New contributors used the "good first issue" label very effectively. We started the Hackfest with most of the 25 "good first issues" unassigned and completed the Hackfest with 14 closed and 10 others in progress. We’ll provide more "good first issues" as we use the Jenkins Wiki migration to welcome new documentation contributors.
Migrating plugin documentation
Plugin documentation is also in transition. Since November 2019, plugins have been moving their documentation into the GitHub repository that hosts the plugin source code. This "documentation as code" approach allows plugin maintainers to include documentation improvements in the same pull requests that implement new capabilities. It assures that documentation changes are reviewed by the same maintainers who review and approve new capabilities.
Hackfest participants submitted pull requests to migrate plugin documentation to GitHub. 10 plugin pull requests are in progress from the Hackfest. 5 plugin pull requests from the Hackfest have been already merged and are awaiting the release of the plugin.
Chuck Norris uses documentation as code
In the spirit of fun and adventure, Oleg Nenashev migrated the "Chuck Norris plugin" to GitHub documentation as code in a live Hackfest presentation May 26, 2020. Links to the recording, the plugin migration guide, and the export tool are available from "Migrating plugins to documentation-as-code".
Documentation updates
Jenkins works with other technologies to solve automation challenges in many different environments. We describe those environments in our "Solution Pages". As part of the Hackfest, we’ve started a series of improvements to the solution pages.
The Docker solutions page now includes updated videos and a better page layout for easier reading and better navigation. Other solution pages will receive similar improvements in the future.
System properties
The global configuration of Jenkins can be modified at startup by defining Java properties. System properties can change system defaults and can provide compatibility "escape hatches" when a new default configuration might be incompatible with existing installations.
Daniel Beck has improved the navigation and user experience of the system properties page as part of the Hackfest. It is now much easier to read and to reference, with embeddable links available with a mouse-over to the right of every property and labels that categorize and classify each property.
Plugin site improvements
During the Hackfest, Gavin Mogan has continued his efforts to improve the Jenkins Plugins Site so that users can easily access plugin changelogs and reported issues. Once this pull request is merged, it will greatly improve the experience of those Jenkins users who want to update plugins and look for documentation about what has changed in them and what are the possible issues they might experience.
Example of the incoming UI for the Jira plugin:
What’s next?
There is still much to do in Jenkins documentation and we need your help to do it. There are many ways to participate in the Jenkins project, including documentation. See the contributing guidelines for detailed instructions. Join the documentation chat for personalized help and encouragement.
The Jenkins project has been also accepted to Google Season of Docs this year. This open-source mentorship program brings together open source and technical writers communities for the benefit of both. We are looking for technical writers who are interested to contribute to the project in September-December 2020. It is a great opportunity to study Documentation-as-code tools and to learn more about contributing to open-source projects. You can find Jenkins project ideas and more information here.
About the authors
