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.
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
A major challenge of software development is that our work is by and large invisible. This makes our folklore essential in business matters. Some of our commonly used arguments and visualizations are digital urban legends rather than solid foundations for informed decisions. Here, we’ll go through a few examples and some measures to address our misconceptions.
How the stories we tell influence our decisions
When you embark on your cloud native journey there will be important choices to make about cloud providers, continuous deployment, environments’ setup and separation. This guide will help you make the right choices by sharing lessons learnt from running cloud native apps in production.
Kubernetes has become the de facto container orchestration platform. When we help clients of different sizes and domains start their cloud native journeys in Kubernetes, we assist them in making sound decisions and technology choices. There is no one-size-fits-all solution when it comes to choosing cloud providers, CI tools, continuous deployment pipelines etc., so it is important to make the right decisions at the start. Failing to do so can be very costly in terms of lost time and money.
How to make the right technical choices on your cloud native journey
Learn how Docker and Kubernetes work and the key benefits they bring. Using real demos, I show how Docker is a great packaging and distribution technology, and how Kubernetes provides a powerful runtime for containerized applications.
Watch this introduction to Docker and Kubernetes at the Trondheim Developer Conference (TDC)
In the world of Agile and DevOps we use many figures, charts and diagrams to argue and reason about our world and how we prioritize and make choices. However, at all levels of the organization, we misuse and misinterpret figures. It’s time to be explicit, measure the right things and act on them. Watch this talk from DevOpsDays Zurich in May 2019.
Watch this talk from DevOpsDays Zurich
Summer is a great time to catch up on reading, whether you’re at the beach, in a summer house, or cozy at home. If your book backlog is on the short side, don’t worry! We compiled a list of great books for summer reading.
Inspiration for your summer reading list
At Praqma we believe in knowledge sharing, and we love to teach our technical expertise. Watch this series of videos to learn how traefik reverse proxy works step by step.
A video seminar to learn how Traefik works
What testing steps should you include in your Continuous Delivery pipeline? Don’t just string together existing manual processes - use simple, collaborative tools to design something better!
A new card game to design Continuous Delivery pipelines
Hear about upcoming events in Scandinavia, latest tech blogs, and training in the field of Continuous Delivery and DevOps