Merge pull request #2226 from OctopusDeploy/runbooks-projects-overvie…

…w-updates

Updates to Projects and Runbooks docs pages

src/pages/docs/projects/index.mdx

@@ -1,121 +1,59 @@
 ---
 layout: src/layouts/Default.astro
 pubDate: 2023-01-01
-modDate: 2023-01-01
+modDate: 2024-04-02
 title: Projects
 navTitle: Overview
 navSection: Projects
 description: Projects let you create and manage your deployment processes, releases, and operations processes.
 navOrder: 50
 ---
-import Projects from 'src/shared-content/concepts/projects.include.md';
+In Octopus, you set up a project for each component you deploy – for example, each application, service, API, or database. In the image below, “Database”, “Product API”, and “Shopping Cart API” are the projects. Each project contains all the information to deploy that application, service, or database.
 
-<Projects />
-
-If you have already created projects, or are joining an existing team, you'll see the existing projects on the projects page.
-
-## Add a project
-
-Before you can define your deployment processes or runbooks, you must create a project:
-
-1. Select **Projects** from the main navigation, and click **ADD PROJECT**.
-1. Give the project a name.
-1. Click **SHOW ADVANCED**.
-1. Add a description for the project.
-1. If you want to change the [Project group](/docs/projects/#project-group) select an existing project group from the drop-down menu.
-1. If you want to change the [Lifecycle](/docs/releases/lifecycles) select an existing lifecycle from the drop down menu.
-1. Click **SHOW LIFECYCLE** if you'd like to see a visual representation of the selected lifecycle.
-1. Click **SAVE** and you will be taken to the newly created project's overview page.
-
-Now that you've created a project, you can define your [deployment process](/docs/projects/deployment-process/) or [runbooks](/docs/runbooks).
-
-## Project settings
-
-You can change the projects settings by accessing the settings menu on the project's main page. The settings you can change are:
-
-- Name.
-- Enable or disable the project to allow or prevent releases and deployments from being created.
-- [Logo](#project-logo)
-- Description
-- [Project Group](#project-group)
-- [Release Versioning](/docs/releases/release-versioning)
-- [Release Notes Template](/docs/releases/release-notes/#templates)
-
-### Deployment settings
-
-- Package re-deployment
-    - Specify to always deploy all packages or to skip any package steps that are already installed.
-- Deployment targets
-    - Specify if deployments are allowed if there are no deployment targets:
-        - Deployments with no target are allowed - There must be at least one enabled healthy target to deploy to in the environment.
-        - Allow deployments to be created when there are no deployment targets - Use this where no steps in the process have targets (or are all run on the Server), or you are dynamically adding targets during deployment.
-- Deployment target status
-    - Choose to skip unavailable, or exclude unhealthy targets from the deployment.
-- [Deployment changes template](/docs/releases/deployment-notes/#Templates)
-    - Specify a template for each deployment's changes.
-- Default failure mode
-    - Specify whether or not to use [guided failure mode](/docs/releases/guided-failures).
-
-## Project logo \{#project-logo}
-
-Customize your project logo to make it easily identifiable amongst other projects.
-
-1. From the project's main page, select **Settings**.
-2. Click the **Logo** section of the settings page.
-3. Select from our built-in icon library paired with your choice of color or upload a custom image.
-4. Click **Save**.
-
-:::div{.hint}
-For custom images, in addition to supporting .jpg and .png files, we also support .gif files. This means you can have an animated icon to add a little flair to your Octopus Deploy instance!
-:::
-
-## Project group \{#project-group}
-
-Project groups are a great way to organize your deployment projects. They have many uses; not only do they visually separate the projects, but you can also configure the dashboard to hide/show specific project groups and configure permissions to restrict access to them.
-
-:::div{.hint}
-The *Default Project* group contains all of the projects that have not been added to another group.
+:::figure
+![Octopus Dashboard](/docs/getting-started/dashboard.png)
 :::
-## Add a project group
-
-1. From the **Projects** tab, click **ADD GROUP**.
-1. Give the group a name and description.
-1. Click **SAVE**.
-
-When the group is first created and doesn't have any projects associated with it, you will need to click **SHOW EMPTY GROUPS** on the projects page to see the group.
-
-## Add projects to a group
-
-After you have created a project group there are a number of ways you can add projects to the group:
 
-- Navigate to the **Projects** page from the main navigation, find the group you want to add the project to, and click **ADD PROJECT**.
-- Edit an existing project by navigating to the project, selecting **Settings** and editing the **Project Group**.
-- Specify the **Project Group** under **Advanced Settings** when you create a new project.
+For each project, you can define:
+- A [deployment process](/docs/projects/deployment-process)
+- [Runbooks](/docs/runbooks) to manage your infrastructure
+- [Variables](/docs/projects/variables/)
+- The [environments](/docs/infrastructure/environments) where you'll deploy the software
 
-### Edit or delete project groups
+Each project has a single deployment process. The process used to deploy to your development environment is the same process used to deploy to your production environment. 
 
-To edit or delete a project group click the project group's overflow menu (...) and select **edit**. From there you can edit the groups name or description. If you need to delete the group, click the overflow menu again and select **Delete**.
+You can dive into the details of your projects from the bird's-eye view of your dashboard.
 
-## Project permissions
-
-For information about project permissions, see [managing users and teams](/docs/security/users-and-teams).
-
-## Clone a project
-
-Projects can be cloned.
-
-1. From the project's menu, select **Settings**.
-2. Click the overflow menu (...), and select **Clone**.
+For advice on how to work with Octopus projects, you can read our [project recommendations](/docs/projects/recommendations). 
 
 :::figure
-![Clone a project](/docs/projects/images/clone-project.png "width=500")
+![Octopus Dashboard](/docs/projects/octopus-projects-list.png)
 :::
 
-:::div{.warning}
-**Version-controlled projects are not currently supported**
-:::
+## Project groups
+Project groups let you organize your projects and keep related components together. For example, you might have a project group for ‘Online Shop’ that has projects for the website, API, and database.
 
-3. Give the new project you are cloning from the original project a name.
-4. Review the settings for the new project and when you are satisfied, click **SAVE**.
+:::figure
+![Octopus Dashboard](/docs/projects/octopus-project-group.png)
+:::
 
-After you've cloned a project, you can see details about where your project was cloned from and which projects have been cloned from your project, by navigating to the project's overview page and selecting **Settings** and looking at the **Cloning History** section.
+Project groups are useful for organizing dashboards and finding related components. You can see the status of your deployments for each component at a glance in one place. You can also configure permissions at the project group level.
+
+## Next steps
+Get started with the basics of [setting up a project](/docs/projects/setting-up-projects) and read our [project recommendations](/docs/projects/recommendations). Then, you can use the links below to add more functionality. 
+
+## Deployments and managing projects
+- [Deployment processes](/docs/projects/deployment-process)
+- [Exporting and importing projects](/docs/projects/export-import)
+- [Variables](/docs/projects/variables)
+- [Tenants](/docs/projects/tenants)
+- [Project triggers](/docs/projects/project-triggers)
+- [Coordinating multiple projects](/docs/projects/coordinating-multiple-projects)
+- [Configuration as Code](/docs/projects/version-control)
+
+## Steps
+- [Steps](/docs/projects/steps)
+- [Built-in step templates](/docs/projects/built-in-step-templates)
+- [Community step templates](/docs/projects/community-step-templates)
+- [Custom step templates](/docs/projects/custom-step-templates)
+- [Update step templates](/docs/projects/updating-step-templates)

src/pages/docs/projects/recommendations/index.mdx

@@ -4,7 +4,7 @@ pubDate: 2023-01-01
 modDate: 2023-01-01
 title: Project recommendations
 description: Projects form a critical element in Octopus Deploy.  Here, we cover some recommendations for projects; getting started on the right foot is vital in helping your Octopus Deploy instance scale.
-navOrder: 10
+navOrder: 20
 ---
 import ProjectRecommendations from 'src/shared-content/octopus-recommendations/project-recommendations.include.md';
 

src/pages/docs/projects/setting-up-projects.md

@@ -0,0 +1,120 @@
+---
+layout: src/layouts/Default.astro
+pubDate: 2023-01-01
+modDate: 2024-04-03
+title: Setting up projects and project groups
+description: How to setup projects and project groups
+navOrder: 10
+---
+
+You can manage your projects by navigating to the **Projects** tab in the Octopus UI:
+
+:::figure
+![Octopus Dashboard](/docs/projects/octopus-projects-list.png)
+:::
+
+If you have already created projects, or are joining an existing team, you’ll see the existing projects on the projects page.
+
+## Add a project
+
+Before you can define your deployment processes or runbooks, you must create a project:
+
+1. Select **Projects** from the main navigation, and click **ADD PROJECT**.
+2. Give the project a name.
+3. Click **SHOW ADVANCED**.
+4. Add a description for the project.
+5. If you want to change the [Project group](#project-group) select an existing project group from the drop-down menu.
+6. If you want to change the [Lifecycle](/docs/releases/lifecycles) select an existing lifecycle from the drop down menu.
+7. Click **SHOW LIFECYCLE** if you’d like to see a visual representation of the selected lifecycle.
+8. Click **SAVE** and you will be taken to the newly created project’s overview page.
+
+Now that you’ve created a project, you can define your [deployment process](/docs/projects/deployment-process/) or [runbooks](/docs/runbooks).
+
+## Project settings
+
+You can change the projects settings by accessing the settings menu on the project’s main page. The settings you can change are:
+
+- Name
+- Enable or disable the project to allow or prevent releases and deployments from being created
+- [Project logo](#project-logo)
+- Description
+- [Project Group](#project-group)
+- [Release Versioning](/docs/releases/release-versioning)
+- [Release Notes Template](/docs/releases/release-notes/#templates)
+
+## Deployment settings
+- Package re-deployment
+   - Specify to always deploy all packages or to skip any package steps that are already installed.
+- Deployment targets
+   - Specify if deployments are allowed if there are no deployment targets:
+      - Deployments with no target are allowed - There must be at least one enabled healthy target to deploy to in the environment.
+      - Allow deployments to be created when there are no deployment targets - Use this where no steps in the process have targets (or are all run on the Server), or you are dynamically adding targets during deployment.
+- Deployment target status
+   - Choose to skip unavailable, or exclude unhealthy targets from the deployment.
+- [Deployment changes template](/docs/releases/deployment-notes/#Templates)
+   - Specify a template for each deployment’s changes.
+- Default failure mode
+   - Specify whether or not to use [guided failure mode](/docs/releases/guided-failures).
+
+## Project logo \{#project-logo}
+Customize your project logo to make it easily identifiable amongst other projects.
+
+1. From the project’s main page, select **Settings**.
+2. Click the **Logo** section of the settings page.
+3. Select from our built-in icon library paired with your choice of color or upload a custom image.
+4. Click **Save**.
+
+:::div{.hint}
+For custom images, in addition to supporting .jpg and .png files, we also support .gif files. This means you can have an animated icon to add a little flair to your Octopus Deploy instance!
+:::
+
+## Project group \{#project-group}
+
+Project groups are a great way to organize your deployment projects. They have many uses; not only do they visually separate the projects, but you can also configure the dashboard to hide/show specific project groups and configure permissions to restrict access to them.
+
+:::div{.hint}
+The *Default Project* group contains all of the projects that have not been added to another group.
+:::
+## Add a project group
+
+1. From the **Projects** tab, click **ADD GROUP**.
+1. Give the group a name and description.
+1. Click **SAVE**.
+
+When the group is first created and doesn't have any projects associated with it, you will need to click **SHOW EMPTY GROUPS** on the projects page to see the group.
+
+## Add projects to a group
+
+After you have created a project group there are a number of ways you can add projects to the group:
+
+- Navigate to the **Projects** page from the main navigation, find the group you want to add the project to, and click **ADD PROJECT**.
+- Edit an existing project by navigating to the project, selecting **Settings** and editing the **Project Group**.
+- Specify the **Project Group** under **Advanced Settings** when you create a new project.
+
+### Edit or delete project groups
+
+To edit or delete a project group click the project group's overflow menu (...) and select **edit**. From there you can edit the groups name or description. If you need to delete the group, click the overflow menu again and select **Delete**.
+
+## Project permissions
+
+For information about project permissions, see [managing users and teams](/docs/security/users-and-teams).
+
+## Clone a project
+
+Projects can be cloned.
+
+1. From the project's menu, select **Settings**.
+2. Click the overflow menu (...), and select **Clone**.
+
+:::figure
+![Clone a project](/docs/projects/images/clone-project.png "width=500")
+:::
+
+:::div{.warning}
+**Version-controlled projects are not currently supported**
+:::
+
+3. Give the new project you are cloning from the original project a name.
+4. Review the settings for the new project and when you are satisfied, click **SAVE**.
+
+After you've cloned a project, you can see details about where your project was cloned from and which projects have been cloned from your project, by navigating to the project's overview page and selecting **Settings** and looking at the **Cloning History** section.

src/pages/docs/runbooks/index.mdx

@@ -1,17 +1,61 @@
 ---
 layout: src/layouts/Default.astro
 pubDate: 2023-01-01
-modDate: 2023-01-01
+modDate: 2024-04-02
 title: Runbooks
 navTitle: Overview
 navSection: Runbooks
 description: With Octopus runbook automation you can automate routine or emergency operations-centric processes, for instance, disaster recovery and database backups.
 navOrder: 90
 ---
-import RunbooksIntro from 'src/shared-content/concepts/runbooks-intro.include.md';
+Deployments are just one piece of the deployment puzzle. You also have to manage day-1 and day-2 operations. Octopus Runbooks lets you automate these routine and emergency operations tasks, giving you one platform for DevOps automation.
 
-<RunbooksIntro />
+A runbook is a set of instructions that help you consistently carry out a task, whether it's routine maintenance or responding to an incident. Octopus provides the platform for your runbooks just as it does for your deployments. 
+
+Runbooks automate routine maintenance and emergency operations tasks, like:
+
+- Infrastructure provisioning
+- Database management
+- Website failover and restoration
+
+:::figure
+![Octopus deployment process](/docs/runbooks/runbooks-screen.png)
+:::
+
+Runbooks help you:
+
+- Make operations more repeatable and reliable
+- Let people self-serve without granting access to the underlying infrastructure
+- Automate tasks so you don't need human intervention
+- Free your teams for more crucial work
+
+## How runbooks work
+You can set permissions so anyone on a team can start a runbook, or you can limit access to specific environments. Octopus handles access control and provides a complete audit trail. This makes runbooks ideal for creating safe and secure, self-service, push-button operations. This also frees up your Ops team from time-consuming, repetitive tasks.
+
+You can also use prompted variables with runbooks if you need human interaction, like a review. Because you don't need to grant access to the underlying infrastructure, reviews and approvals can happen in Octopus, too. This keeps the whole process in one place. The audit log stores changes to runbooks, requests to run them, and approvals, for complete transparency.
+
+## Types of runbooks
+There are 3 common types of runbooks:
+
+- **Routine operations** - where you replace manual operations and ClickOps with runbooks. The goal is to move all toil into runbooks so you don’t need to remote into servers or click through cloud management portals. You can use Octopus to bring these tasks into one place and make them self-service or automatic.
+- **Emergency operations** - runbooks can reduce stress during an incident. You can have runbooks that restart a server, or perform a graceful failover to your standby region when there's a major incident.
+- **Infrastructure provisioning** - for elastic or transient environments, you can use runbooks to deploy templates for cloud infrastructure on Azure, AWS, or Google Cloud. Or, you might apply a Terraform template, destroy a Terraform resource, or create Terraform plans.
+
+Learn more about the ways you can use runbooks in our [runbooks examples](/docs/runbooks/runbook-examples).
+
+## Getting started
+Runbooks belong to projects. To create or manage your runbooks, navigate to **Project ➜ Operations ➜ Runbooks ➜ Add Runbook**.
 
 To create a runbook, navigate to **Project ➜ Operations ➜ Runbooks ➜ Add Runbook**.
 
-![Add Runbook](/docs/runbooks/runbooks-list.png "width=500")
+:::figure
+![Add Runbook](/docs/runbooks/create-a-runbook.png)
+:::
+
+## Learn more
+- [Runbooks versus deployments](/docs/runbooks/runbooks-vs-deployments) - Learn how runbooks differ from deployments
+- [Runbooks permissions](/docs/runbooks/runbook-permissions) - Understand how to manage permissions
+- [Runbooks variables](/docs/runbooks/runbook-variables) - Learn how to manage variables
+- [Runbooks publishing](https://octopus.com/docs/runbooks/runbook-publishing) - Learn about snapshots for runbooks 
+- [Scheduled runbook triggers](https://octopus.com/docs/runbooks/scheduled-runbook-trigger) - Define an unattended behavior for your runbook
+- [Runbook examples](https://octopus.com/docs/runbooks/runbook-examples) - Learn about the ways you can use runbooks