typeof NaN === 'number'

The Jenkins team has done a good job documenting basic pipeline structure and functionality.  Kudos to them for that, it’s improved massively over the past year.  I think it’s pretty easy to get started now.

Let’s talk about the plug-ins.  To do most anything useful in Jenkins requires plug-ins, lots and lots of plug-ins.  Before the Jenkinsfile you could look through the plug-in documentation and see screenshots or just discover the functionality by browsing the UI.  Now that plug-ins are exposing steps to be used in a Jenkinsfile, the poor state of plug-in documentation is not good enough.

It seems that the authors of Jenkins understood this would be a problem and they exposed a snippet generator.  All the registered steps can generate a snippet with arguments.  Unfortunately, these are also poorly documented.  Due to Groovy’s flexibility a single step may be able to be used in multiple ways.  My experience has been that plug-in authors don’t document all the variations.  I spend 90% of the time digging through mailing lists and bug trackers to figure out the correct syntax.

I’ve spent some time thinking about how I could possibly help improve the situation.  It seems like such a daunting task.  I think the best I can do is submit PRs to improve plug-in documentation as I find issues.  It’d be impossible to start from top to bottom to improve them.  Examples may be the key.  Something structured like a cookbook with common use cases.  The recipes should list specific plug-in versions.  Plug-ins could link to recipes from their information page.  Maybe that’s a third party project.