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

Restructure the Jenkins User Documentation's 'User Handbook'

    XMLWordPrintable

    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

            ggaskell Giles Gaskell created issue -
            ggaskell Giles Gaskell made changes -
            Field Original Value New Value
            Description * 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 WEBSITE-399 but on a smaller scale.
            ** 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
            Is it possible to nest other top-level sections which are currently in the 'User Handbook' into this section? I was thinking that the following sections could be nested, since they mostly cover topics relating to utilizing Jenkins as a user / developer who wants to build something:
            Pipeline
            It would be a good opportunity to reduce some of the duplicated content in this section and the Guided Tour above.
            Blue Ocean
            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 you want to emphasize.
            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).
            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
            * 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
            *** Pipeline
            **** 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
            **** 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).
            ** 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
            ggaskell Giles Gaskell made changes -
            Description * 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
            *** Pipeline
            **** 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
            **** 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).
            ** 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
            The new structure of this User Handbook (below) was taken from [this discussion|https://groups.google.com/forum/#!topic/jenkinsci-docs/fI_gfQ0_ZWk] 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
            *** Pipeline
            **** 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
            **** 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).
            ** 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.
            **
            ggaskell Giles Gaskell made changes -
            Description The new structure of this User Handbook (below) was taken from [this discussion|https://groups.google.com/forum/#!topic/jenkinsci-docs/fI_gfQ0_ZWk] 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
            *** Pipeline
            **** 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
            **** 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).
            ** 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 new structure of this User Handbook (below) was taken from [this discussion|https://groups.google.com/forum/#!topic/jenkinsci-docs/fI_gfQ0_ZWk] 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
            *** Pipeline
            **** 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
            **** 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
            *** The details of this information could initially come from relevant articles and blog posts, such as:
            **** [Tuning Jenkins Garbage Collection for Responsiveness and Stability with Large Instances|https://jenkins.io/blog/2016/11/21/gc-tuning/].
            ** 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
            ggaskell Giles Gaskell made changes -
            Description The new structure of this User Handbook (below) was taken from [this discussion|https://groups.google.com/forum/#!topic/jenkinsci-docs/fI_gfQ0_ZWk] 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
            *** Pipeline
            **** 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
            **** 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
            *** The details of this information could initially come from relevant articles and blog posts, such as:
            **** [Tuning Jenkins Garbage Collection for Responsiveness and Stability with Large Instances|https://jenkins.io/blog/2016/11/21/gc-tuning/].
            ** 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
            The new structure of this User Handbook (below) was taken from [this discussion|https://groups.google.com/forum/#!topic/jenkinsci-docs/fI_gfQ0_ZWk] 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*
            *** *Pipeline*
            **** 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*
            **** 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*
            *** The details of this information could initially come from relevant articles and blog posts, such as:
            **** [Tuning Jenkins Garbage Collection for Responsiveness and Stability with Large Instances|https://jenkins.io/blog/2016/11/21/gc-tuning/].
            ** *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.
            ggaskell Giles Gaskell made changes -
            Description The new structure of this User Handbook (below) was taken from [this discussion|https://groups.google.com/forum/#!topic/jenkinsci-docs/fI_gfQ0_ZWk] 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*
            *** *Pipeline*
            **** 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*
            **** 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*
            *** The details of this information could initially come from relevant articles and blog posts, such as:
            **** [Tuning Jenkins Garbage Collection for Responsiveness and Stability with Large Instances|https://jenkins.io/blog/2016/11/21/gc-tuning/].
            ** *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 new structure of this User Handbook (below) was taken from [this discussion|https://groups.google.com/forum/#!topic/jenkinsci-docs/fI_gfQ0_ZWk] 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*
            *** *Pipeline*
            **** 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*
            **** 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*
            *** The details of this information could initially come from relevant articles and blog posts, such as:
            **** [Tuning Jenkins Garbage Collection for Responsiveness and Stability with Large Instances|https://jenkins.io/blog/2016/11/21/gc-tuning/].
            // //
            ** *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.
            ggaskell Giles Gaskell made changes -
            Description The new structure of this User Handbook (below) was taken from [this discussion|https://groups.google.com/forum/#!topic/jenkinsci-docs/fI_gfQ0_ZWk] 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*
            *** *Pipeline*
            **** 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*
            **** 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*
            *** The details of this information could initially come from relevant articles and blog posts, such as:
            **** [Tuning Jenkins Garbage Collection for Responsiveness and Stability with Large Instances|https://jenkins.io/blog/2016/11/21/gc-tuning/].
            // //
            ** *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 new structure of this User Handbook (below) was taken from [this discussion|https://groups.google.com/forum/#!topic/jenkinsci-docs/fI_gfQ0_ZWk] 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*
             *** *Pipeline*
             **** 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*
             **** 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*
             *** The details of this information could initially come from relevant articles and blog posts, such as:
             **** [Tuning Jenkins Garbage Collection for Responsiveness and Stability with Large Instances|https://jenkins.io/blog/2016/11/21/gc-tuning/].


             ** *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.
            ggaskell Giles Gaskell made changes -
            Description The new structure of this User Handbook (below) was taken from [this discussion|https://groups.google.com/forum/#!topic/jenkinsci-docs/fI_gfQ0_ZWk] 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*
             *** *Pipeline*
             **** 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*
             **** 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*
             *** The details of this information could initially come from relevant articles and blog posts, such as:
             **** [Tuning Jenkins Garbage Collection for Responsiveness and Stability with Large Instances|https://jenkins.io/blog/2016/11/21/gc-tuning/].


             ** *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 new structure of this User Handbook (below) was taken from [this discussion|https://groups.google.com/forum/#!topic/jenkinsci-docs/fI_gfQ0_ZWk] 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*
             *** *Pipeline*
             **** 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*
             **** 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*
             *** The details of this information could initially come from relevant articles and blog posts, such as:
             **** [Tuning Jenkins Garbage Collection for Responsiveness and Stability with Large Instances|https://jenkins.io/blog/2016/11/21/gc-tuning/].
            \\ \\
             ** *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.
            ggaskell Giles Gaskell made changes -
            Description The new structure of this User Handbook (below) was taken from [this discussion|https://groups.google.com/forum/#!topic/jenkinsci-docs/fI_gfQ0_ZWk] 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*
             *** *Pipeline*
             **** 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*
             **** 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*
             *** The details of this information could initially come from relevant articles and blog posts, such as:
             **** [Tuning Jenkins Garbage Collection for Responsiveness and Stability with Large Instances|https://jenkins.io/blog/2016/11/21/gc-tuning/].
            \\ \\
             ** *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 new structure of this User Handbook (below) was taken from [this discussion|https://groups.google.com/forum/#!topic/jenkinsci-docs/fI_gfQ0_ZWk] 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*
             *** *Pipeline*
             **** 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*
             **** 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*
             *** The details of this information could initially come from relevant articles and blog posts, such as:
             **** [Tuning Jenkins Garbage Collection for Responsiveness and Stability with Large Instances|https://jenkins.io/blog/2016/11/21/gc-tuning/].
             ** *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.

             
            ggaskell Giles Gaskell made changes -
            Description The new structure of this User Handbook (below) was taken from [this discussion|https://groups.google.com/forum/#!topic/jenkinsci-docs/fI_gfQ0_ZWk] 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*
             *** *Pipeline*
             **** 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*
             **** 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*
             *** The details of this information could initially come from relevant articles and blog posts, such as:
             **** [Tuning Jenkins Garbage Collection for Responsiveness and Stability with Large Instances|https://jenkins.io/blog/2016/11/21/gc-tuning/].
             ** *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 new structure of this User Handbook (below) was taken from [this discussion|https://groups.google.com/forum/#!topic/jenkinsci-docs/fI_gfQ0_ZWk] 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*
            *** *Pipeline*
            **** 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*
            **** 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*
            *** The details of this information could initially come from relevant articles and blog posts, such as:
            **** [Tuning Jenkins Garbage Collection for Responsiveness and Stability with Large Instances|https://jenkins.io/blog/2016/11/21/gc-tuning/].
            \\ \\
            ** *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.
            ggaskell Giles Gaskell made changes -
            Assignee Giles Gaskell [ ggaskell ]
            ggaskell Giles Gaskell made changes -
            Assignee Giles Gaskell [ ggaskell ]
            ggaskell Giles Gaskell made changes -
            Description The new structure of this User Handbook (below) was taken from [this discussion|https://groups.google.com/forum/#!topic/jenkinsci-docs/fI_gfQ0_ZWk] 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*
            *** *Pipeline*
            **** 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*
            **** 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*
            *** The details of this information could initially come from relevant articles and blog posts, such as:
            **** [Tuning Jenkins Garbage Collection for Responsiveness and Stability with Large Instances|https://jenkins.io/blog/2016/11/21/gc-tuning/].
            \\ \\
            ** *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 new structure of this User Handbook (below) was taken from [this discussion|https://groups.google.com/forum/#!topic/jenkinsci-docs/fI_gfQ0_ZWk] 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*
            *** *Pipeline*
            **** 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*
            **** 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*
            *** The details of this information could initially come from relevant articles and blog posts, such as:
            **** [Tuning Jenkins Garbage Collection for Responsiveness and Stability with Large Instances|https://jenkins.io/blog/2016/11/21/gc-tuning/].
            \\ \\
            ** *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.
            ggaskell Giles Gaskell made changes -
            Description The new structure of this User Handbook (below) was taken from [this discussion|https://groups.google.com/forum/#!topic/jenkinsci-docs/fI_gfQ0_ZWk] 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*
            *** *Pipeline*
            **** 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*
            **** 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*
            *** The details of this information could initially come from relevant articles and blog posts, such as:
            **** [Tuning Jenkins Garbage Collection for Responsiveness and Stability with Large Instances|https://jenkins.io/blog/2016/11/21/gc-tuning/].
            \\ \\
            ** *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.
            The new structure of this User Handbook (below) was taken from [this discussion|https://groups.google.com/forum/#!topic/jenkinsci-docs/fI_gfQ0_ZWk] on the jenkinsci-docs Google Group.

            (!) If you are editing this *Description* field, please try to do so using *Text* mode only. If you're in *Visual* mode and click *Save*, the formatting of the bulleted list below will degrade.

            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*
            *** *Pipeline*
            **** 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*
            **** 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*
            *** The details of this information could initially come from relevant articles and blog posts, such as:
            **** [Tuning Jenkins Garbage Collection for Responsiveness and Stability with Large Instances|https://jenkins.io/blog/2016/11/21/gc-tuning/].
            \\ \\
            ** *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.
            ggaskell Giles Gaskell made changes -
            Description The new structure of this User Handbook (below) was taken from [this discussion|https://groups.google.com/forum/#!topic/jenkinsci-docs/fI_gfQ0_ZWk] on the jenkinsci-docs Google Group.

            (!) If you are editing this *Description* field, please try to do so using *Text* mode only. If you're in *Visual* mode and click *Save*, the formatting of the bulleted list below will degrade.

            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*
            *** *Pipeline*
            **** 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*
            **** 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*
            *** The details of this information could initially come from relevant articles and blog posts, such as:
            **** [Tuning Jenkins Garbage Collection for Responsiveness and Stability with Large Instances|https://jenkins.io/blog/2016/11/21/gc-tuning/].
            \\ \\
            ** *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.
            The new structure of this User Handbook (below) was taken from [this discussion|https://groups.google.com/forum/#!topic/jenkinsci-docs/fI_gfQ0_ZWk] on the jenkinsci-docs Google Group.

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

            ----
            (!) If you are editing this *Description* field, please try to do so using *Text* mode only. If you're in *Visual* mode and click *Save*, the formatting of the bulleted list below will degrade.
            ----

            * *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*
            *** *Pipeline*
            **** 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*
            **** 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*
            *** The details of this information could initially come from relevant articles and blog posts, such as:
            **** [Tuning Jenkins Garbage Collection for Responsiveness and Stability with Large Instances|https://jenkins.io/blog/2016/11/21/gc-tuning/].
            \\ \\
            ** *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.
            ggaskell Giles Gaskell made changes -
            Description The new structure of this User Handbook (below) was taken from [this discussion|https://groups.google.com/forum/#!topic/jenkinsci-docs/fI_gfQ0_ZWk] on the jenkinsci-docs Google Group.

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

            ----
            (!) If you are editing this *Description* field, please try to do so using *Text* mode only. If you're in *Visual* mode and click *Save*, the formatting of the bulleted list below will degrade.
            ----

            * *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*
            *** *Pipeline*
            **** 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*
            **** 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*
            *** The details of this information could initially come from relevant articles and blog posts, such as:
            **** [Tuning Jenkins Garbage Collection for Responsiveness and Stability with Large Instances|https://jenkins.io/blog/2016/11/21/gc-tuning/].
            \\ \\
            ** *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.
            ----
            (!) If you are editing this *Description* field, please try to do so using *Text* mode only. If you're in *Visual* mode and click *Save*, the formatting of the bulleted list below will degrade.
            ----

            The new structure of this User Handbook (below) was taken from [this discussion|https://groups.google.com/forum/#!topic/jenkinsci-docs/fI_gfQ0_ZWk] 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*
            *** *Pipeline*
            **** 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*
            **** 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*
            *** The details of this information could initially come from relevant articles and blog posts, such as:
            **** [Tuning Jenkins Garbage Collection for Responsiveness and Stability with Large Instances|https://jenkins.io/blog/2016/11/21/gc-tuning/].
            \\ \\
            ** *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.
            ggaskell Giles Gaskell made changes -
            Description ----
            (!) If you are editing this *Description* field, please try to do so using *Text* mode only. If you're in *Visual* mode and click *Save*, the formatting of the bulleted list below will degrade.
            ----

            The new structure of this User Handbook (below) was taken from [this discussion|https://groups.google.com/forum/#!topic/jenkinsci-docs/fI_gfQ0_ZWk] 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*
            *** *Pipeline*
            **** 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*
            **** 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*
            *** The details of this information could initially come from relevant articles and blog posts, such as:
            **** [Tuning Jenkins Garbage Collection for Responsiveness and Stability with Large Instances|https://jenkins.io/blog/2016/11/21/gc-tuning/].
            \\ \\
            ** *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.
            (!) If you are editing this *Description* field, please try to do so using *Text* mode only. If you're in *Visual* mode and click *Save*, the formatting of the bulleted list below will degrade.

            ----

            The new structure of this User Handbook (below) was taken from [this discussion|https://groups.google.com/forum/#!topic/jenkinsci-docs/fI_gfQ0_ZWk] 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*
            *** *Pipeline*
            **** 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*
            **** 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*
            *** The details of this information could initially come from relevant articles and blog posts, such as:
            **** [Tuning Jenkins Garbage Collection for Responsiveness and Stability with Large Instances|https://jenkins.io/blog/2016/11/21/gc-tuning/].
            \\ \\
            ** *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.
            ggaskell Giles Gaskell made changes -
            Description (!) If you are editing this *Description* field, please try to do so using *Text* mode only. If you're in *Visual* mode and click *Save*, the formatting of the bulleted list below will degrade.

            ----

            The new structure of this User Handbook (below) was taken from [this discussion|https://groups.google.com/forum/#!topic/jenkinsci-docs/fI_gfQ0_ZWk] 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*
            *** *Pipeline*
            **** 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*
            **** 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*
            *** The details of this information could initially come from relevant articles and blog posts, such as:
            **** [Tuning Jenkins Garbage Collection for Responsiveness and Stability with Large Instances|https://jenkins.io/blog/2016/11/21/gc-tuning/].
            \\ \\
            ** *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.
            (!) 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 degrade.

            ----

            The new structure of this User Handbook (below) was taken from [this discussion|https://groups.google.com/forum/#!topic/jenkinsci-docs/fI_gfQ0_ZWk] 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*
            *** *Pipeline*
            **** 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*
            **** 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*
            *** The details of this information could initially come from relevant articles and blog posts, such as:
            **** [Tuning Jenkins Garbage Collection for Responsiveness and Stability with Large Instances|https://jenkins.io/blog/2016/11/21/gc-tuning/].
            \\ \\
            ** *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.
            ggaskell Giles Gaskell made changes -
            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 degrade.

            ----

            The new structure of this User Handbook (below) was taken from [this discussion|https://groups.google.com/forum/#!topic/jenkinsci-docs/fI_gfQ0_ZWk] 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*
            *** *Pipeline*
            **** 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*
            **** 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*
            *** The details of this information could initially come from relevant articles and blog posts, such as:
            **** [Tuning Jenkins Garbage Collection for Responsiveness and Stability with Large Instances|https://jenkins.io/blog/2016/11/21/gc-tuning/].
            \\ \\
            ** *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.
            (!) 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|https://groups.google.com/forum/#!topic/jenkinsci-docs/fI_gfQ0_ZWk] 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*
            *** *Pipeline*
            **** 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*
            **** 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*
            *** The details of this information could initially come from relevant articles and blog posts, such as:
            **** [Tuning Jenkins Garbage Collection for Responsiveness and Stability with Large Instances|https://jenkins.io/blog/2016/11/21/gc-tuning/].
            \\ \\
            ** *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.
            ggaskell Giles Gaskell made changes -
            Assignee Giles Gaskell [ ggaskell ]
            Status To Do [ 10003 ] In Progress [ 3 ]
            ggaskell Giles Gaskell made changes -
            Remote Link This issue links to "GitHub pull request 1138 (Web Link)" [ 17727 ]
            ggaskell Giles Gaskell made changes -
            Link This issue relates to WEBSITE-409 [ WEBSITE-409 ]
            ggaskell Giles Gaskell made changes -
            Status In Progress [ 3 ] In Review [ 10005 ]
            ggaskell Giles Gaskell made changes -
            Remote Link This issue links to "GitHub pull request 1328 (Web Link)" [ 19930 ]
            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.
            ggaskell Giles Gaskell made changes -
            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|https://groups.google.com/forum/#!topic/jenkinsci-docs/fI_gfQ0_ZWk] 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*
            *** *Pipeline*
            **** 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*
            **** 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*
            *** The details of this information could initially come from relevant articles and blog posts, such as:
            **** [Tuning Jenkins Garbage Collection for Responsiveness and Stability with Large Instances|https://jenkins.io/blog/2016/11/21/gc-tuning/].
            \\ \\
            ** *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.
            (!) 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|https://groups.google.com/forum/#!topic/jenkinsci-docs/fI_gfQ0_ZWk] 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*
            *** The details of this information could initially come from relevant articles and blog posts, such as:
            **** [Tuning Jenkins Garbage Collection for Responsiveness and Stability with Large Instances|https://jenkins.io/blog/2016/11/21/gc-tuning/].
            \\ \\
            ** *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.
            ggaskell Giles Gaskell made changes -
            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|https://groups.google.com/forum/#!topic/jenkinsci-docs/fI_gfQ0_ZWk] 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*
            *** The details of this information could initially come from relevant articles and blog posts, such as:
            **** [Tuning Jenkins Garbage Collection for Responsiveness and Stability with Large Instances|https://jenkins.io/blog/2016/11/21/gc-tuning/].
            \\ \\
            ** *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.
            (!) 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|https://groups.google.com/forum/#!topic/jenkinsci-docs/fI_gfQ0_ZWk] 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*
            *** The details of this information could initially come from relevant articles and blog posts, such as:
            **** [Tuning Jenkins Garbage Collection for Responsiveness and Stability with Large Instances|https://jenkins.io/blog/2016/11/21/gc-tuning/].
            \\ \\
            ** *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.
            ggaskell Giles Gaskell made changes -
            Resolution Fixed [ 1 ]
            Status In Review [ 10005 ] Done [ 10004 ]

              People

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

                Dates

                Created:
                Updated:
                Resolved: