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

Add a new landing page for the Jenkins user documentation

    Details

    • Similar Issues:

      Description

      Create a new landing page for the Jenkins user documentation site with introductory material about using Jenkins and a brief overview of the site.

      The name of this page would be 'Jenkins User Documentation' (for reasons explained in this discussion), whose link in the TOC ideally would sit above the Guided Tour heading.

      This page should cover introductory material about Jenkins, such as:

      • A description of what Jenkins is (which currently exists in brief form at the top of the current 'Index' page) and
      • An overview of content in (and with links to) the remainder of the Jenkins user documentation (which doesn't exist yet).

      In parallel to this, update the current 'Index' page (whose description of what Jenkins is would have been moved to the new 'Jenkins User Documentation' landing page) and begin the page with the 'Guided Tour' content - whose title should be renamed 'Getting Started' or 'Getting Started with the Guided Tour'.

        Attachments

          Activity

          Hide
          bitwiseman Liam Newman added a comment -

          This task should also address the "What is Jenkins Pipeline?" section on the landing page:

          bitwiseman:
          Maybe this section belongs at the top of "Create your first Pipeline" https://jenkins.io/doc/pipeline/tour/hello-world/ ? Might be out of scope for this PR.

          gilesgas:
          I agree that this segment doesn't belong here and I'll deal with this in a separate PR.

          Putting this segment at the top of the next "Creating your first Pipeline" page would be more appropriate, but since this section of the documentation (i.e. Guided Tour) is more like a set of mini tutorials, perhaps we should consider "merging" this "What is a Jenkins Pipeline?" segment into the introductory material of the Pipeline section of the User Handbook? (This'll entail a little re-writing.)

          By doing this, we could:

          Link to the description/definition for what a Jenkins Pipeline is in the User Handbook (from the Guided Tour) and
          Remove partially duplicated content throughout this documentation, which should ultimately make it easier to maintain.

          Giles Gaskell - I think the tutorial needs to talk a bit what what Jenkins Pipeline is in order for users to make sense of it, but I like the idea of linking off to any in-depth description. Maybe whatever we keep could be more show-and-tell, mixed into the tutorial, instead of block of text.

          Show
          bitwiseman Liam Newman added a comment - This task should also address the "What is Jenkins Pipeline?" section on the landing page: bitwiseman: Maybe this section belongs at the top of "Create your first Pipeline" https://jenkins.io/doc/pipeline/tour/hello-world/ ? Might be out of scope for this PR. gilesgas: I agree that this segment doesn't belong here and I'll deal with this in a separate PR. Putting this segment at the top of the next "Creating your first Pipeline" page would be more appropriate, but since this section of the documentation (i.e. Guided Tour) is more like a set of mini tutorials, perhaps we should consider "merging" this "What is a Jenkins Pipeline?" segment into the introductory material of the Pipeline section of the User Handbook? (This'll entail a little re-writing.) By doing this, we could: Link to the description/definition for what a Jenkins Pipeline is in the User Handbook (from the Guided Tour) and Remove partially duplicated content throughout this documentation, which should ultimately make it easier to maintain. Giles Gaskell - I think the tutorial needs to talk a bit what what Jenkins Pipeline is in order for users to make sense of it, but I like the idea of linking off to any in-depth description. Maybe whatever we keep could be more show-and-tell, mixed into the tutorial, instead of block of text.
          Hide
          ggaskell Giles Gaskell added a comment - - edited

          Thanks for the addition above Liam Newman. I've kept a little bit of a description about Jenkins Pipelines in the relevant Guided Tour page with a link to more information in the Pipelines page of the User Handbook. Following on from that...

          I've also fleshed out the actual description of what a 'Jenkins Pipeline' actually is, because the current description:

          Jenkins Pipeline is a suite of plugins which supports implementing and integrating continuous delivery pipelines into Jenkins

          still doesn't really explain what a pipeline is. I'm aware this might be obvious to people who are well-versed in CI/CD technologies, but to users/developers who aren't, it would help to spell things out a little more.

          Therefore, I've come up with the following more detailed description:

          Jenkins Pipeline (or simply "Pipeline" with a capital "P") is a suite of plugins which supports implementing and integrating continuous delivery pipelines into Jenkins.

          A continuous delivery pipeline is an automated expression of your process for getting software from version control right through to your users and customers. Every change to your software (committed in source control) goes through a complex process on its way to being released. This process involves building the software in a reliable and repeatable manner, as well as the progression of the built software (called a "build") through multiple stages of testing and deployment.

          I'm happy for feedback on or improvement to this definition.

          Show
          ggaskell Giles Gaskell added a comment - - edited Thanks for the addition above Liam Newman . I've kept a little bit of a description about Jenkins Pipelines in the relevant Guided Tour page with a link to more information in the Pipelines page of the User Handbook. Following on from that... I've also fleshed out the actual description of what a 'Jenkins Pipeline' actually is, because the current description: Jenkins Pipeline is a suite of plugins which supports implementing and integrating continuous delivery pipelines into Jenkins still doesn't really explain what a pipeline is. I'm aware this might be obvious to people who are well-versed in CI/CD technologies, but to users/developers who aren't, it would help to spell things out a little more. Therefore, I've come up with the following more detailed description: Jenkins Pipeline (or simply "Pipeline" with a capital "P") is a suite of plugins which supports implementing and integrating continuous delivery pipelines into Jenkins. A continuous delivery pipeline is an automated expression of your process for getting software from version control right through to your users and customers. Every change to your software (committed in source control) goes through a complex process on its way to being released. This process involves building the software in a reliable and repeatable manner, as well as the progression of the built software (called a "build") through multiple stages of testing and deployment. I'm happy for feedback on or improvement to this definition.
          Hide
          ggaskell Giles Gaskell added a comment -

          Pull request with this content was already merged.

          Show
          ggaskell Giles Gaskell added a comment - Pull request with this content was already merged.

            People

            • Assignee:
              ggaskell Giles Gaskell
              Reporter:
              ggaskell Giles Gaskell
            • Votes:
              0 Vote for this issue
              Watchers:
              2 Start watching this issue

              Dates

              • Created:
                Updated:
                Resolved: