Jenkins plugin developers - let’s look at our documentation process around the plugins. It needs improvements! Wouldn’t it be great if we could automate more of the release process related to documentation?
Today it seems like the majority of us release the plugin, THEN go to the plugin wiki and update the documentation - and that some forget this last step. But what if your release process automatically updated the documentation?
Would you like to make sure the user documentation is matching the current version of the plugin? Documentation is obviously only a benefit for the users, if the help we offer them on wiki is actually helpful - wrong or old documentation is just confusing.
Many plugins have a good changelog on the wiki, for example the Changelog in the Git Plugin and our own plugins, like the Changes section on the Pretested Integration Plugin wiki.
In my experience, this type of information is important and is actually being read and checked upon upgrading or when a user has problems with a plugin. So: Why do we not auto generate the majority of that information based on the git commits that go into the release?
_The thoughts above were part of my motivation for suggesting the “Automate plugin documentation” topic at the “Jenkins code camp” that took place during the “Jenkins User Event Scandinavia 2015”.
We’re posting this blog to hear your opinion on the matter. Is automated documentation a good idea? Would you use it?
1) The Maven jpi/hpi packs the documentation as part of the Maven release goal. It only converts and packs when running a release, to save development cycles.
2) The packed documentation is released as an individual artifact to the plugin repository, not as part of the plugin itself. This provides more flexibility for later updates to the documentation.
3) Documentation is automatically converted from GitHub Flavored Markdown to static HTML before it is packed. GitHub Flavored Markdown is well known, and the community uses GitHub.
4) Your Maven configuration must specify which Markdown files to use. E.g. defaults to docs/plugin.md becomes docs-plugin.html, and docs/changelog.md becomes docs-changelog.html. One or more Markdown files can be combined to one HTML file. This will make it flexible to separate or re-use documentation and to include auto generated documentation as well.
5) There will be a Maven goal to generate and verify the documentation, and to preview it during development. This will enable us to validate that it looks nice.
6) A new Confluence wiki plugin can show the static HTML pages as part of the wiki page itself. The documentation matching the latest plugin release is automatically chosen. Using the Confluence plugin is optional, so you don’t have to use this new way of documenting.
7) Documentation can be (re)released without a new plugin release, to fix typos or for post-edits. The new documentation artifact has a new release number. By some convention - matching the plugin version - a new version of the plugin documentation will then automatically be used by the wiki plugin.
8) If you chose to put all documentation with the plugin in Markdown, the plugin wiki page will simply be the usual jenkins-plugin-info at the top and the new Confluence wiki plugin showing the converted Markdown. You can also mix the approaches of course.
9) You can edit smaller pieces of the documentation as you implement bugfixes and features, since the documentation can now be edited together with the source code. This way you avoid the big boring hurdle before the release: updating large chunks of documentation. You can even require from the contributing developers that documentation is always updated alongside the code changes.
10) The changelog section on the wiki can now be generated, using a script or maybe Maven, by writing a changelog.md file. We could extend it further, to update JIRA issue statuses (e.g. resolved) based on what goes into the release.
11) When documentation follows the plugin release, we can provide version specific documentaion. This can be very useful for people that can’t or won’t upgrade a plugin for whatever reason. Today the wiki, if even up-to-date, just shows the newest documentation so it can be hard to find out how to use older versions of the plugin.
Would you use the new work flow?
In my opinion a lot of plugins are either fully lacking documentation or the documentation is somewhere between confusing and outright wrong because it isn’t kept up-to-date.
A long time ago, I asked for thoughts and tips on the Jenkins dev list - see the mail here
The mail thread more or less explains a useful solution that targets most of the features I would like, but it doesn’t maintain the documentation on the Jenkins Plugin Wiki where we think it currently belongs.
Do you have a tendency to use the backlog as an eternal placeholder? If so, you probably have a lot of clutter that’s creating a lot of frustrations for your end-users. In this post we’ll show you how to clean up your Jira issues and reduce the backlog with some basic JQL queries.
Tips to improve project management in the Atlassian suite
How to test Kubernetes artifacts like Helm charts and YAML manifests in your CI pipelines with a low-overhead, on-demand Kubernetes cluster deployed with KIND - Kubernetes in Docker.
Low overhead, on-demand Kubernetes clusters deployed on CI Workers Nodes with KIND
Had enough of sluggish polling? With instant Artifactory event triggers you can give responsiveness in Jenkins a real boost. Here’s an easy way to set it up.
A super easy configuration guide
With the arrival of microservices code is becoming disposable. Does this mean that we no longer need maintainable code? Is it the end of refactoring?
Still relevant or increasingly redundant?
In software development tight coupling is one of our biggest enemies. On the function level it makes our application hard to change and fragile. Unfortunately, tight coupling is like the entropy of software development, so we have always have to be working to reduce it.
How to safely introduce modular architecture to legacy software
I am an Atlassian certified trainer and over the years I have been spending much time with clients and their Jiras. In this blogpost, I have collected some small tips and tricks that will make your Jira usage better.
Jira Software is a powerful tool deployed in so many organizations, yet in day to day usage people are missing out on improvements, big and small.
In this post, I’ll take a closer look at the version of Jenkins X using Tekton, to give you an idea of how the general development, build, test, deploy flow looks like with Jenkins X. How does it feel to ship your code to production using a product coming from the Jenkins community that has very little Jenkins in it?
A crash course in Jenkins X and how to test it out on a local Kubernetes cluster
In this blog I will show you how to create snapshots of Persistent volumes in Kubernetes clusters and restore them again by only talking to the api server. This can be useful for either backups or when scaling stateful applications that need “startup data”.
Sneak peak at CSI Volume snapshotting Alpha feature
When I read Fowler’s new ‘Refactoring’ book I felt sure the example from the first chapter would make a good Code Kata. However, he didn’t include the code for the test cases. I can fix that!
Writing tests for ‘Theatrical Players’
Nicole Forsgren and the Accelerate DORA team has just released the newest iteration of the State of DevOps report. The report investigates what practices make us better at delivering valuable software to our users as measured by business outcomes. Read on for our analysis of the report, and how it can be best put to use.
The latest drivers of software delivery performance
Hear about upcoming events in Scandinavia, latest tech blogs, and training in the field of Continuous Delivery and DevOps