Docs: clarified and expanded continuous deployment overview and integ…

docs/user/continuous-deployment.rst

@@ -2,63 +2,77 @@
 
 :orphan:
 
+===============================
 Continuous Documentation Deployment
-===================================
+===============================
 
-Read the Docs is a *Continuous Documentation Deployment* platform for your software project.
-Every time you change something in your documentation, Read the Docs will detect your change and build your documentation.
+Read the Docs is a *Continuous Documentation Deployment* platform for your software project.  
+Every time you update your documentation, Read the Docs automatically detects the change and rebuilds your site.
 
-The Continuous Integration and Continuous Deployment (CI/CD) features are configured with your repository provider,
-such as GitHub, Bitbucket or GitLab.
-With each change committed to your repository, we are notified by the configured *webhook*.
+-----------------------
+How Continuous Deployment Works
+-----------------------
 
-When we receive a *webhook*, we match it to a project's *Integration*,
-and the following steps happen:
+Read the Docs integrates with repository providers such as **GitHub**, **GitLab**, and **Bitbucket**.  
+Each time you push a new commit, the configured *webhook* notifies Read the Docs, which then triggers a new build.
+
+When we receive a webhook, we match it to the project’s *Integration* and perform the following steps:
 
 * :doc:`Build </builds>` the latest commit.
-* Synchronize your :doc:`versions </versions>` based on the latest tag and branch data in Git.
-* Run your :doc:`automation rules</automation-rules>`.
-* Auto-cancel any currently running builds of the same version.
-* Add a log entry to the integration's :guilabel:`Recent Activity`.
+* Synchronize your :doc:`versions </versions>` based on new tags and branches in Git.
+* Run your :doc:`automation rules </automation-rules>`.
+* Automatically cancel any currently running builds for the same version.
+* Add a log entry to the integration’s :guilabel:`Recent Activity`.
+
+-----------------------
+Documentation as Code
+-----------------------
+
+Read the Docs follows the principle of *Documentation as Code (Docs-as-Code)* —  
+treating documentation with the same tools, workflows, and discipline as your source code.
+
+By managing your documentation alongside your codebase, you gain:
+
+* **Unified reviews:** documentation changes go through the same pull request process.
+* **Faster feedback:** preview new docs before merging using :doc:`pull request previews </pull-requests>`.
+* **Automation:** documentation stays up-to-date automatically after each code change.
 
-Documentation as code
----------------------
+Keeping your documentation integrated with your CI/CD pipeline ensures it evolves with your project — no extra steps, no forgotten updates.
 
-Documentation fits into any CI/CD pipeline by following a process known as *Documentation as Code (Docs as code)*.
-This means that the documentation's life cycle is the same as your software project.
-By managing these changes in the same life cycle,
-you can benefit from **documentation and source code being part of the same code review process**.
+-----------------------
+Automated Versioning
+-----------------------
 
-Having an automated and short feedback loop for your documentation allows you to
-keep it updated with minimal effort.
-This allows more iteration on documentation,
-and increases overall value from the documentation you write.
+Read the Docs allows your documentation to stay perfectly aligned with your software’s release cycle.  
+When you tag a new release in Git, Read the Docs can automatically:
 
-As part of this quick feedback loop,
-you can preview documentation changes immediately using :doc:`pull request previews </pull-requests>`.
+* Create and publish a :doc:`new documentation version </versions>`.
+* Trigger automation rules via :doc:`/automation-rules`.
+* Archive and preserve previous versions for user access.
 
-Automated versioning
---------------------
+You can manage versioning automatically or manually depending on your release workflow.  
+All published versions remain accessible through the :term:`flyout menu` and can be enhanced using :doc:`/addons`.
 
-With Read the Docs you will be able to fully align your project's **release cycle** with your documentation.
-For instance, a new version of a software project can build and publish a :doc:`new documentation version </versions>`.
+-----------------------
+Troubleshooting & Verification
+-----------------------
 
-When you release a new version for your project,
-you are likely also adding a version tag to your Git repository.
-These Git events can be configured to build and publish your documentation automatically with :doc:`/automation-rules`.
-If you use a versioning scheme, you can configure it as part of the automation process.
+If your webhook isn’t triggering builds:
 
-Whether you choose to handle versioning automatically or with manual control is up to you.
+1. Verify that your repository is correctly connected under **Project > Integrations**.
+2. Check your repository’s webhook settings — you should see a **Read the Docs** webhook.
+3. Push a small commit and check your build logs on the Read the Docs dashboard.
 
-Read the Docs will store your version history and make it possible for users to visit archived versions of your documentation.
-Your version setup is ultimately captured by the :term:`flyout menu`,
-and can be integrated in your documentation with :doc:`/addons`.
+Common issues:
+- **Webhook not firing:** check OAuth connection or make sure your repo is public.
+- **Incorrect version built:** verify your default branch setting.
+- **Builds stuck:** use the “Cancel Build” option and re-trigger manually.
 
-.. seealso::
+-----------------------
+See Also
+-----------------------
 
-    :doc:`/guides/setup/git-repo-manual`
-        Information on setting up your Git repository to make Read the Docs automatically build your documentation project.
-    :doc:`/automation-rules`
-        Information on setting up your Git repository to make Read the Docs automatically build your documentation project.
-    :doc:`/flyout-menu`
-        Discover the functionality of the Flyout menu and the ways that it can be customized.
+* :doc:`/guides/setup/git-repo-manual` — set up your Git repository for automatic builds.
+* :doc:`/automation-rules` — configure automated build rules and triggers.
+* :doc:`/flyout-menu` — customize your project’s version switcher.
+* [Integration Overview](https://docs.readthedocs.io/en/stable/integrations.html)