Update getting started

Author: FejZa

docs/00-introduction.md

@@ -4,21 +4,44 @@ title: Introduction
 slug: /
 ---
 
-Once Unity Tools for Azure DevOps has been installed to your organization, you'll have access to a set of
-build and release tasks for Unity related operations. The extension provides the following tasks for use in your pipelines:
+# Introduction to CI/CD Automation for Unity Projects
 
-Please check each tasks documentation page and for examples on how to use them. Also make sure to checkout our [Examples](./examples.md) collection with useful pipeline definitions you can copy-paste and adjust to your needs.
+Continuous Integration and Continuous Deployment (CI/CD) are pivotal in modern software development, ensuring that teams can build, test, and deliver applications efficiently and reliably. For Unity developers, adopting CI/CD workflows can significantly streamline the creation and distribution of games and interactive experiences, while minimizing risks and maximizing productivity.
 
-## Build Tasks
+This Azure DevOps extension was specifically designed to enhance the CI/CD process for Unity-based projects. Before diving into how to use the extension, let’s explore why CI/CD automation is important and how it benefits Unity developers.
 
-- [Unity Build](unity-build-task.md)
-- [Unity CMD](unity-cmd-task.md)
+## Why CI/CD Automation Matters
 
-## Testing Tasks
+In traditional development workflows, building, testing, and deploying applications often involve manual steps that are time-consuming and error-prone. With CI/CD automation, these processes are streamlined and standardized, offering the following advantages:
 
-- [Unity Test](unity-test-task.md)
+1. **Faster Iterations:** Automated pipelines allow developers to focus on creating and refining features instead of spending time on manual builds and deployments. Changes can be integrated, tested, and deployed within minutes.
 
-## Utility Tasks
+2. **Improved Code Quality:** Continuous integration ensures that every change is tested as soon as it’s pushed to the repository. This immediate feedback loop helps identify bugs and regressions early in the development cycle.
 
-- [Unity Activate License](unity-activate-license-task.md)
-- [Unity Get Project Version](unity-get-project-version-task.md)
+3. **Enhanced Collaboration:** Teams can work more cohesively by integrating their changes frequently, reducing merge conflicts and maintaining a cleaner codebase.
+
+4. **Consistent Builds:** Automation eliminates the inconsistencies that arise from manual builds, ensuring that the same process is followed every time a build is created.
+
+5. **Reduced Risk:** By automating deployment, you reduce the likelihood of human error, leading to more reliable and predictable releases.
+
+6. **Scalability:** As your Unity project grows, manual processes can quickly become unmanageable. CI/CD pipelines can handle the increased complexity, allowing your team to scale without bottlenecks.
+
+## Benefits for Unity Developers
+
+Unity projects pose unique challenges when it comes to CI/CD due to their reliance on specific project configurations, asset management, and platform-specific builds. This extension addresses these challenges and offers the following Unity-specific benefits:
+
+1. **Automated Builds Across Platforms:** Unity projects often target multiple platforms, such as PC, console, mobile, and VR/AR devices. CI/CD pipelines can automate the build process for all target platforms, saving time and reducing errors.
+
+2. **Seamless Asset Handling:** Unity projects include large assets that need to be properly managed and integrated into builds. Automation ensures that these assets are consistently processed and optimized.
+
+3. **Improved Testing:** From unit tests to playmode tests, CI/CD pipelines can automate testing workflows to ensure that your project runs as expected across various configurations and platforms.
+
+4. **Streamlined Distribution:** With automated pipelines, you can directly distribute builds to testers, stakeholders, or app stores, making the deployment process fast and hassle-free.
+
+5. **Support for Collaboration:** Unity is often used by multidisciplinary teams comprising developers, artists, and designers. CI/CD workflows help ensure that all team members’ contributions are integrated smoothly, maintaining project stability.
+
+## Conclusion
+
+CI/CD automation isn’t just a convenience—it’s a necessity for modern Unity development. By adopting automated workflows, your team can unlock new levels of efficiency, quality, and scalability. This Azure DevOps extension is here to help you achieve these goals, providing tailored solutions for the unique needs of Unity projects.
+
+In the following sections, we’ll guide you through setting up and using this extension to build powerful CI/CD pipelines tailored to your Unity projects. Let’s get started!

docs/01-getting-started/01-installation.md

@@ -12,51 +12,14 @@ This documentation assumes you have some knowledge of setting up pipelines using
 
 :::
 
-## What is it?
-
-It's an extension to [Azure DevOps](https://azure.microsoft.com/en-us/services/devops/) that adds build and release tasks specifially for [Unity](https://unity.com/) projects. That way it enables implementation of continuous integration and deployment pipelines for an improved workflow that saves time and money.
-
----
-
-## How to install
-
 The extension is published to the Visual Studio Marketplace and can be installed from there:
 
 1. Open the extension [Unity Tools for Azure DevOps](https://marketplace.visualstudio.com/items?itemName=DinomiteStudios.64e90d50-a9c0-11e8-a356-d3eab7857116) in the marketplace and select `Get it free` to start the installation process.
 
-   ![Extension in Marketplace](../../static/img/vs-marketplace-get-extension.png)
+   ![Extension in Marketplace](./img/vs-marketplace-get-extension.png)
 
 2. Select the Azure DevOps organization you want to install the extension to and proceed by selecting `Install`. *(You may also download the extension if you are using Azure DevOps Server).*
 
-   ![Install to organization](../../static/img/vs-marketplace-install.png)
-
-3. The extension is now installed and you are ready to create your first Unity pipeline.
-
----
-
-## Supported Unity Versions
-
-Unity Tools for Azure DevOps supports building Unity projects starting from `2017.2.0f1` up to the `latest release` of the Unity editor.
-
----
-
-## Supported Agents
-
-The extension generally supports Microsoft hosted agents as well as custom agents. Some features may not be available when using hosted agents for older Unity versions and platforms that require setting up e.g. specific SDKs on the machine for builds to work. In such cases, we recommend using a custom agent with full control over tools and software installed.
-
-### Supported Platforms for Hosted Agents
-
-- Standalone Windows
-- Standalone macOS
-- Standalone Linux
-- Universal Windows Platform
-
-:::caution
-
-Please note that a Unity Plus / Pro seat with at least one available activation is required to build using hosted agents. This is a requirement by Unity not this extension. The agent will activate the seat on build and release it again once done.
-
-:::
-
-### Supported Platforms for Custom Agents
+   ![Install to organization](./img/vs-marketplace-install.png)
 
-- All Unity Platforms supported
+3. The extension is now installed and you are ready to create your first Unity pipeline.

docs/01-getting-started/02-unity-support.md

@@ -2,4 +2,17 @@
 id: unity-support
 title: Supported Unity Versions
 sidebar_label: Supported Unity Versions
----
+---
+
+# Supported Unity versions
+
+All included automation tasks in the extension have been tested and verified against the following Unity versions. Any other versions are not officially supported, they may or may not work.
+
+| Unity Version  | Supported | Notes |
+|----------------|:---------:|-------|
+| Unity 6        |     ✅     |       |
+| Unity 2022 LTS |     ✅     |       |
+| Unity 2021 LTS |     ✅     |       |
+| Unity 2020 LTS |     ✅     |       |
+| Unity 2019 LTS |     ✅     |       |
+| Unity 2018 LTS |     ✅⚠     | Support will be dropped with the next major release. Please consider updating your project to a newer Unity version.      |

docs/01-getting-started/03-agent-support.md

@@ -2,4 +2,26 @@
 id: agent-support
 title: Supported Agents
 sidebar_label: Supported Agents
----
+---
+
+# Supported agents
+
+The extension generally supports Microsoft hosted agents as well as custom agents. Some features may not be available when using hosted agents for older Unity versions and platforms that require setting up e.g. specific SDKs on the machine for builds to work. In such cases, we recommend using a custom agent with full control over tools and software installed.
+
+| Unity Version | Supported | Notes |
+|---------------|:---------:|-------|
+| Hosted Agents |     ✅     | Minimum agent version: 2.144.0      |
+| Custom Agents |     ✅     | Minimum agent version: 2.144.0      |
+
+## Software requirements for custom agents
+
+Microsoft hosted agents come with everything you need already set up. If you are setting up your own agent, do make sure it meets the following Software requirements.
+
+| Software / SDK |
+|----------------|
+| Unity Hub  |
+| git  |
+
+:::info
+Additional software or SDKs may be needed depending on the platform you are targeting with your build. The rule of thumb is, whatever you need to build your project on your own development machine, you'll need to make sure it is installed on the agent as well.
+:::