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

Restructure the Jenkins User Documentation's 'User Handbook'

    Details

    • Similar Issues:

      Description

      If you wish to edit this Description field, please try to do so using Text mode only. If you're in Visual mode and you click Save, the formatting of the bulleted list below will be saved in a degraded state.


      The new structure of this User Handbook (below) was taken from this discussion on the jenkinsci-docs Google Group.

      However, what you see below will change based on the direction of this discussion.

      • User Handbook
        • Getting Started
          • This section should just be a single page defining the roles / personas of Jenkins - i.e. users (who are typically developers who want to build something) vs managers (administrators who want to administer their Jenkins site).
          • This page should also describe / provide an overview of the remaining structure of this Handbook. A bit like the landing page described in WEBSITE-399 but more specific to the content in the User Handbook.

        • Installing Jenkins
          • This page / set of pages should cover all supported procedures for installing Jenkins on all supported platforms.
          • We could probably also mention and link to other un-supported platforms - but we should avoid documenting them (since we don't support them).
          • This section should be detailed and cover what's not covered in the Guided Tour.
          • There is an existing 'Advanced Jenkins Installation', which is empty so I'm not sure what was intended to be on that page. If there is a reason for such page, then it could go into this section.

        • Using Jenkins (update Jan 24 2018 - this section now contains all non-admin everyday Jenkins usage topics that don't fit into the Pipeline and Blue Ocean chapters below.)
          • Pipeline (update Jan 24 2018 - this chapter will no longer be nested within Using Jenkins)
            • It would be a good opportunity to reduce some of the duplicated content in this section and the Guided Tour above - initially thinking about 'What is a Jenkins Pipeline?' (covered in WEBSITE-399).

          • Blue Ocean (update Jan 24 2018 - this chapter will no longer be nested within Using Jenkins)
            • Pull out the plugin installation content from this section and move it to the Managing Jenkins section.
            • Perhaps reverse the order of the Pipeline and Blue Ocean subsections based on what part should be emphasized.

        • Managing Jenkins
          • Keep these topics 'as is' (with additions like installing Blue Ocean). These topics all relate to managing / administering Jenkins.

        • Jenkins system administration
          • This is renamed from 'Operating Jenkins' section (which didn't sound like Jenkins system administration, which is what these topics actually cover).

        • Scaling Jenkins
        • Appendix
          • It might be worthwhile pulling the 'Pipeline Syntax' page out into this Appendix. Doing so will make it more prominent as it's already linked from multiple places throughout the jenkins.io documentation (and presumably elsewhere too). It's also essentially a form of reference material.

        • Glossary
      • Reference
        • This is renamed from ‘Resources’ (which sounds a little too non-specific).
        • Keep the link to ‘Pipeline Syntax’ here - since it would be good to be able to generate the Handbook as a PDF which includes the Appendix.
        • The Steps reference looks a bit scary - I think I’ll need a bit more time to familiarize myself with this aspect of Jenkins before dealing with this.

      The current plan is to ditch the empty Best Practices, since what we should be documenting throughout the User Handbook are best practices for using Jenkins.

      The section on Jenkins Use-Cases can probably be omitted/hidden for the time being until some genuine content comes through.

        Attachments

          Issue Links

            Activity

            Hide
            ggaskell Giles Gaskell added a comment - - edited

            Following a discussion with Liam Newman, the Using Jenkins chapter will now cover all non-administration aspects of Jenkins usage which aren't directly related to Pipeline or Blue Ocean Jenkins features - e.g. Using credentials.

            Being able to nest the Pipeline and Blue Ocean chapters within Using Jenkins would be a 'nice to have' from a documentation structure perspective, but taking into consideration the existing design of the Jenkins User Documentation (i.e. inflexible left-hand TOC and especially no search function), doing so would make the Pipeline and Blue Ocean chapters less 'discoverable'.

            Therefore, as part of PR 1328, the introductory sections of each chapter will clearly indicate the contents of the chapters.

            Show
            ggaskell Giles Gaskell added a comment - - edited Following a discussion with Liam Newman , the Using Jenkins chapter will now cover all non-administration aspects of Jenkins usage which aren't directly related to Pipeline or Blue Ocean Jenkins features - e.g. Using credentials. Being able to nest the Pipeline and Blue Ocean chapters within Using Jenkins would be a 'nice to have' from a documentation structure perspective, but taking into consideration the existing design of the Jenkins User Documentation (i.e. inflexible left-hand TOC and especially no search function), doing so would make the Pipeline and Blue Ocean chapters less 'discoverable'. Therefore, as part of PR 1328 , the introductory sections of each chapter will clearly indicate the contents of the chapters.

              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: