feat: Content improvements for the docs contributors

en/contributors/documentation/deployment-azure.md

@@ -1,24 +1,25 @@
-# Deployment in Azure
-- [Step-by-Step Guide to Deploying Azure Web Apps (Windows) with IIS](#step-by-step-guide-to-deploying-azure-web-apps-windows-with-iis)
-  - [Setting up a new Azure Web App (Windows) with IIS](#setting-up-a-new-azure-web-app-windows-with-iis)
-  - [Adjusting the Web App Configuration](#adjusting-the-web-app-configuration)
-  - [Modifying the GitHub Action](#modifying-the-github-action)
+# Deployment
 
-# Step-by-Step Guide to Deploying Azure Web Apps (Windows) with IIS
+Our team has explored various deployment options, ultimately selecting the method detailed in this guide for its efficacy. Additionally, for demonstration purposes, you can refer to the [Deployment to GitHub Pages](deployment-azure.md#deployment-to-github-pages) section for alternative deployment strategies you can use to showcase your updates.
 
-This guide assumes you already have permission to access the Azure subscription.
+## Deploying to Azure Web Apps (Windows) with IIS
 
-## Setting up a new Azure Web App (Windows) with IIS
+This guide is crafted for individuals who already have access to the Azure subscription. It provides step-by-step instructions for setting up a new Azure Web App, specifically tailored for staging environments. Note that the process for setting up a production environment is similar, but requires a distinct web app name.
 
-These instructions pertain to the staging environment. For the production environment, follow the same steps, but with a different web app name.
+> [!NOTE]
+> The deployment process outlined here is already established and running, hosted on Azure and sponsored by the .NET Foundation. This guide serves primarily as a reference for maintainers in the event that a new deployment setup is required.
+
+### Setting up a new Azure Web App
+
+Follow these instructions carefully to establish your Azure Web App in a staging environment. For deploying in a production environment, replicate these steps with an alternate web app name for differentiation.
 
 1. Navigate to the [Azure Portal](https://portal.azure.com/)
 1. Select **Create a resource**
 1. Choose **Create a Web App**
 1. In the Basic Tab
    - Choose your existing subscription and resource group
    - Under Instance Details, enter:
-      - Name: **stride-website-staging**
+      - Name: **stride-docs-staging**
       - Publish: **Code**
       - Runtime stack: **ASP.NET V4.8**
       - OS: **Windows**
@@ -27,7 +28,7 @@ These instructions pertain to the staging environment. For the production enviro
       - Click **Next**
 1. In the Deployment Tab - This step can be completed later if preferred.
    - Enable Continuous deployment
-   - Select account, organisation `Stride`, repository `stride-website` and branch `staging-next`
+   - Select account, organisation `Stride`, repository `stride-docs` and branch `staging`
    - Click **Next**
 1. In the Monitoring Tab
    - Leave all settings as default
@@ -43,30 +44,57 @@ These instructions pertain to the staging environment. For the production enviro
    - Click **Create**
    - The GitHub Action will be added to the repository and run automatically. It will fail at this stage, but this will be resolved in the subsequent steps.
 
-## Adjusting the Web App Configuration
+> [!CAUTION]
+> If you have completed the **Deployment Tab** process, ensure that the deployment profile includes the **DeleteExistingFiles** property. This property may need to be set to `False` or `True` depending on the specific requirements of your deployment. For instance, Stride Docs deployment retains files from previous deployments, allowing multiple versions like `4.2`, `4.1`, etc., to be maintained. Adjust this setting based on your deployment needs.
+
+### Adjusting the Web App Configuration
 
 1. Proceed to the newly created Web App
 1. Click on **Configuration**
 1. Select **General Settings**
-1. Change the Http Version to **2.0**
+1. Change the `Http version` to **2.0**
+1. Change `Ftp state` to **FTPS only**
+1. Change `HTTPS Only` to **On**
 1. Click **Save** to apply the changes
 
-## Modifying the GitHub Action
+### Modifying the GitHub Action
 
-The previous step will have added a GitHub Action to the repository, which will fail at this point. You need to modify the GitHub Action to correct the issue.
+The previous step will have added a GitHub Action to your repository, which might fail initially. To address this, you need to modify the GitHub Action:
 
 1. Navigate to the repository
-1. Select Actions
+1. Select **Actions**
 1. You have the option to stop the currently running action
-1. Locate the new GitHub Action *(within this folder Stride Website -> staging-next repo -> .github -> workflows)* which was automatically generated by the Azure Portal. We will need to reference the properties app-name and publish-profile and disable the push trigger.
+1. Locate the new GitHub Action file *(stride-docs/blob/master/.github/workflows/some-file-name.yml)* that was automatically generated by Azure Portal. We need to extract the `app-name` and `publish-profile` values from it and disable the push trigger.
    - To disable the push trigger, retain only **workflow_dispatch** (manual trigger) as shown below:
     ```
     on:
     #  push:
     #    branches:
-    #      - staging-next
+    #      - staging
         workflow_dispatch:
     ```
-1. Open the `stride-website-staging-azure.yml` workflow and update it with the properties from the previous step. Save your changes.
-1. This workflow may also need to be added to the production branch master if it is not already there.
-1. Execute the workflow stride-website-staging-azure.yml. Ensure you select the correct branch staging-next and click **Run workflow**. This action will deploy the website to the Azure Web App.
+1. Open the `stride-docs-staging-azure.yml` workflow and update it with the values obtained in the previous step. Save your changes.
+1. This workflow might also need to be added to the `master` branch if it is not already present.
+1. Execute the workflow `stride-docs-staging-azure.yml`. Ensure you select the correct branch `staging` and click **Run workflow**. This action will deploy the website to the Azure Web App.
+
+## Deployment to GitHub Pages
+
+To showcase your updates, especially helpful for design changes pending review, you can deploy the docs website either to your infrastructure or to GitHub Pages, a free hosting service. Once deployed, share the link with us for review.
+
+### Prerequisites
+
+In your `stride-docs` repository:
+
+1. Navigate to **Settings** → **Actions** → **General** → **Workflow Permissions**
+   - Choose **Read and write permissions**
+
+### Run GitHub Action
+
+1. Go to **Actions**, select **Build Stride Web for GitHub Staging**
+   - Click **Run workflow**; you may optionally select a branch
+2. Monitor the build logs while the action is in progress
+3. Upon successful build, a `gh-pages` branch will be created
+4. Navigate to **Settings** → **Pages**
+   - Choose the `gh-pages` branch with the root option and click **Save**
+5. After saving, an internal GitHub Action **pages build and deployment** is automatically created and triggered, deploying the content to the GitHub Pages website
+6. The website will be accessible at `https://[your-username].github.io/stride-docs`

en/contributors/documentation/documentation-generation-pipeline.md

@@ -13,7 +13,7 @@ The script serves two main purposes:
 
 Here's a straightforward explanation of how the documentation generation process works.
 
-The `/en` folder serves as the repository for the primary documentation files. When documentation for another language (e.g., Japanese) is built, the files from `/en` are copied over to a temporary folder, for example, `/jp-tmp`. This ensures that the non-English versions will contain all the files present in the `/en` folder. Files that have been translated (found in folders like `/jp`) will overwrite their English counterparts in the temp folder.
+The `/en` folder serves as the repository for the primary documentation files. When documentation for another language (e.g., Japanese) is built, the files from `/en` are copied over to a temporary folder, for example, `/jp-tmp`. This ensures that the non-English versions will contain all the files present in the `/en` folder. Files that have been translated (found in folders like `/jp`) will overwrite their English counterparts in the temp folder `/jp-tmp`.
 
 DocFX is invoked multiple times, once for each language, to create the documentation. The generated documents are stored in the `_site` folder, organized according to the latest version information obtained from `version.json`. For example:
 
@@ -26,12 +26,12 @@ DocFX is invoked multiple times, once for each language, to create the documenta
 
 This section outlines the file processing carried out by DocFX during the documentation generation:
 
-- **Table of Contents (TOC) Files:** 4 files processed
-- **Assets:** 1607 items (images, videos, etc.) included
-- **Conceptual Files:** 304 files processed, resulting in 304 HTML files
+- **Table of Contents (TOC) Files:** 7 files processed
+- **Assets:** 1620 items (images, videos, etc.) included
+- **Conceptual Files:** 358 files processed, resulting in 304 HTML files
 - **Warnings (No API Metadata):** 44 instances encountered
 - **Warnings (API Metadata):** 200 instances of missing or incorrect references
-- **API Files:** 2821 files processed, resulting in 2133 HTML files
+- **API Files:** 2825 files processed, resulting in 2133 HTML files
 
 ## Docs Build Workflow
 
@@ -132,7 +132,8 @@ graph TB
     R -->|No| T
     S --> T
     T --> X{{docfx build}}
-    X --> Y
+    X --> X1{{docfx pdf}}
+    X1 --> Y
     Y --> Z
     end
 ```

en/contributors/documentation/index.md

@@ -25,6 +25,5 @@ Various Stride systems rely on content fetched and processed from either the Str
 
 1. https://doc.stride3d.net/latest/en/index.json
    - This JSON file is crucial for integrating the Stride Docs search functionality with the Stride Website. It ensures that search results are comprehensive, including relevant information from both the Stride website and Stride Docs.
-
 1. https://doc.stride3d.net/latest/en/ReleaseNotes/ReleaseNotes.md
    - The **Stride Launcher** utilizes this file when you click a release notes button.

en/contributors/documentation/roadmap.md

@@ -6,6 +6,4 @@ This is a proposal for our website roadmap and ongoing website development plan.
 - Streamline the website by decoupling media from the site
   - Host videos on YouTube
   - Host images in Azure Blob Storage or another location
-- Optimize the website for possible deployment on Azure Static Web Apps
-
-
+- Optimize the website for possible deployment on Azure Static Web Apps

en/contributors/documentation/troubleshooting-and-faq.md

@@ -16,6 +16,4 @@ Any issue should be added to Stride Website [GitHub issues](https://github.com/s
 
 **Q:** I just want to fix a typo in a post. Do I need to follow your installation steps?
 
-**A:** *No, you can fix the typo directly on the GitHub website. However, you will still need to fork the repo, make your update on the main branch or a new branch, and then create a pull request. You can follow this guide for [minor updates](content.md#small-updates).*
-
-
+**A:** *No, you can fix the typo directly on the GitHub website. However, you will still need to fork the repo, make your update on the main branch or a new branch, and then create a pull request. You can follow this guide for [minor updates](content.md#small-updates).*