Uploaded image for project: 'Jenkins Website'
  1. Jenkins Website
  2. WEBSITE-185

Improve the presentation/usability of pipeline steps reference

    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

            Activity

            Hide
            kwhetstone 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.

            Show
            kwhetstone 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.
            Hide
            danielbeck Daniel Beck added a comment -

            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":

            • ArtifactArchiver
            • Fingerprinter

            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.

            Show
            danielbeck Daniel Beck added a comment - 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": ArtifactArchiver Fingerprinter 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.

              People

              • Assignee:
                kwhetstone Kristin Whetstone
                Reporter:
                bitwiseman Liam Newman
              • Votes:
                0 Vote for this issue
                Watchers:
                3 Start watching this issue

                Dates

                • Created:
                  Updated: