I agree, there are a lot of things that could be done on this page to make it easier to figure out what's going on. The plugin steps not be indexed like that on the side of the page; I believe that modifying that is a change within the index page generation. The main page might be better served as an introduction, maybe even part of the implementation of WEBSITE-252. Minimally, get the plugin steps off the side of the page.
A common issue I've at least I've heard a few people talking about in the past (and I think Liam you had some good suggestions around this) is actually providing examples of the plugin steps on the pages with the plugins. Right now, you have to go to either a tutorial or to the plugin's GitHub page to see what to do. Examples can be added to the page; however, currently the information isn't presented in a standard way. I could try to import a file end point to get more information (I think a lot of examples are on the readme page), or do some sort of linkage to a tutorial page/plugin information page/GitHub repo where users could see how to use these commands.
As to outlining the plugins like a type of javadoc, I don't know the limitations of jenkins.io. Right now it's just in asciidoc, and honestly could be whatever format is the clearest for our users. Would having a section like this not mesh with the rest of the website? The layout currently can be confusing. Any other suggestions to make the pages easier to process.