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.