Introducing Tutorials in the Jenkins User Documentation
Regular perusers of the Jenkins User Documentation may have noticed the presence of the Tutorials part (between the Guided Tour and User Handbook) that appeared in the last couple of months and gradually began to get populated with much of my recent work, writing Jenkins tutorials.
My name’s Giles and I’ve been a technical writer in the software development field for several years now. I’ve always been passionate about technical writing and more recently, the technologies that go into developing written content and automating its generation - like Jenkins! I was a former Atlassian and recently joined CloudBees as a Senior Technical Writer, working remotely from the "Sydney Office", with my current focus on the Jenkins User Documentation.
Why tutorials?
My exposure to Jenkins and its usage over the years has been patchy at best. During this time, however, I’ve had some degree of experience as a user of various continuous delivery (CD) tools like Jenkins and am reasonably familiar with the advantages these tools can offer software development teams.
I’ve also found that while many software developers are familiar with the broader concept of "developer operations" (or simply "devops"), fewer seem familiar with the concepts of CD and related tools to facilitate devops within organizations.
The CD process is based on the fundamental flow of building the application > testing it > delivering it, where typically:
-
The building part involves compiling the application and/or ensuring all necessary libraries and dependencies are in place for the application to run as intended.
-
The testing part involves testing the built application with automated tests to ensure that changes implemented by developers function as expected.
-
The delivering part involves packaging or presenting the application in a way that can be delivered to customers or other users for any kind of purpose.
Now, as one of the major contributors to the Jenkins User Documentation (and faced with a reasonably steep learning curve), it quickly became apparent about the lack of accessible documentation to hand-hold people relatively new to Jenkins through this CD process. I couldn’t find anything in the Jenkins User Documentation to demonstrate how Jenkins implements this process on a simple app that delivers an end result.
With the guidance and assistance of helpful colleagues, I therefore decided to embark on creating a series of Jenkins tutorials to help fill these documentation and knowledge gaps. These tutorials are based on Daniele Procida’s description of how tutorials should be presented in his blog post "What nobody tells you about documentation").
Introductory tutorials
The first set of tutorials on the Tutorials overview page demonstrate how to implement this fundamental CD process in Jenkins on a simple application for a given technology stack.
So far, there’s one for Java with Maven and another for Node.js and React with npm. Another for Python will be added to this list in the near future.
These tutorials define your application’s entire CD process (i.e. your Pipeline)
in a Jenkinsfile, whose Groovy-like Declarative Pipeline syntax is checked in
to your Git source repository. Managing your Pipeline with your application’s
source code like this forms the fundamentals of "Pipeline as code".
The Introductory tutorials also cover how to use some powerful features of Jenkins, like Blue Ocean, which makes it easy to connect to an existing cloud, web or locally hosted Git repository and create your Pipeline with limited knowledge of Pipeline syntax.
Advanced tutorials
Also soon to be released will be the first Advanced tutorial on building
multibranch Pipelines in Jenkins. This tutorial takes the "Pipeline as code"
concept to a new level, where a single Jenkinsfile (defining the entire CD
process across all branches of your application’s Git repository) consists of
multiple stages which are selectively executed based on the branch that Jenkins
is building.
Additional tutorials that demonstrate more advanced features of Jenkins and how to manage your Pipelines with greater sophistication and flexibility will be added to this section in future.
Summing up
You can access all currently available tutorials from the Tutorials overview page in the Jenkins User Documentation. It’s worthwhile checking that page from time to time as it’ll be updated whenever a new tutorial is published.
Also, if you have any suggestions for tutorials or other content you’d like to see in the documentation, please post your suggestions in the jenkinsci/docs gitter channel.
The Sydney Office team meeting at Carriageworks - from left to right, Giles
Gaskell, Nicholae Pascu, Michael Neale and James Dumay