Details
-
Type:
Improvement
-
Status: To Do (View Workflow)
-
Priority:
Major
-
Resolution: Unresolved
-
Component/s: design
-
Labels:None
-
Similar Issues:
Description
Looking at: https://jenkins.io/doc/pipeline/steps/
In chrome the l
This page is oddly structured and the layout is odd (over indented) and the presentation gives no context on how to use this list. (see attached
Given that people working in pipeline are developing in Groovy/Java we should make this kind of reference look like other Groovy/Java documentation (see https://docs.oracle.com/javase/7/docs/api/java/lang/Object.html) or consider how the JobDSL api reference is presented (https://jenkinsci.github.io/job-dsl-plugin).
Attachments
Issue Links
- is duplicated by
-
WEBSITE-355 Nested references are unreadable with Pipeline step reference
-
- Done
-
Activity
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.
Kristin Whetstone
added a comment - 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. 
The Pipeline step docs generator should be changed such that each 'delegate' (first argument) to the 'step' metastep appears as an individual step.
For example, there'd be a new file for core (which doesn't exist today), and it would list the following "steps":
There'd also be a new file for the JUnit plugin, and it work have the JUnitResultArchiver "step".
All of these would (if I hadn't removed them from output for now) show on workflow-basic-steps doc as variants of 'step' calls, which is where no user would expect to find them. A side effect of the current behavior is also that many plugins implementing basic Pipeline compatibility don't even show up, as they use general 'step' support (possibly with Symbol annotation to make it look nice) to make them work in Pipeline. These should, in the step doc, be elevated to "first class" steps to be easier to discover and read the doc for.