From ca742bb0845b03b1ca81c6cfc1e69753c76017da Mon Sep 17 00:00:00 2001
From: Andreia <andreia.velasco@canonical.com>
Date: Fri, 24 Apr 2026 11:07:22 +0200
Subject: [PATCH] Update README

Rough draft.
---
 README.md | 63 ++++++++++++++++++++++++++++++++++++++-----------------
 1 file changed, 44 insertions(+), 19 deletions(-)

diff --git a/README.md b/README.md
index e74fa995..81863364 100644
--- a/README.md
+++ b/README.md
@@ -1,39 +1,64 @@
 # Canonical's Sphinx Starter Pack
 
-*A pre-configured repository to build and publish documentation with Sphinx.*
+[![Test starter pack](https://github.com/canonical/sphinx-docs-starter-pack/actions/workflows/test-starter-pack.yml/badge.svg)](https://github.com/canonical/sphinx-docs-starter-pack/actions/workflows/test-starter-pack.yml)
 
-## Description
+A pre-configured repository to build documentation with [Sphinx] and publish it on [Read The Docs].
 
-The Documentation starter pack includes:
+The Starter Pack contains build instructions, extensions with styling and configuration options, and automatic documentation checks.
 
-* A bundled [Sphinx] theme, configuration, and extensions
-* Support for both reStructuredText (reST) and MyST Markdown
-* Build checks for links, spelling, and inclusive language
-* Customisation support layered over a core configuration
+## Using the Starter Pack
 
-See the full documentation: https://canonical-starter-pack.readthedocs-hosted.com/
+This repository contains example documentation that can be built out of the box.
 
-## Structure
+To try it out, clone it locally and navigate to the `/docs` folder:
 
-This section outlines the structure of this repository, and some key files.
+```shell
+git clone git@github.com:canonical/sphinx-docs-starter-pack.git
+cd docs
+```
 
-### `docs/`
+Then, run the command
 
-This directory contains the documentation for the starter pack itself.
+```shell
+make run
+```
 
-To view it in your browser, navigate to this directory and type `make run`.
+This will create a Python virtual environment, install necessary dependencies, build the documentation, and serve it in a local webserver.
 
-### `.github/workflows/`
+You can access it in your browser at http://127.0.0.1:8000.
 
-This directory contains files used for documentation build checks via GitHub's CI.
+To learn more about how to install and configure the Starter Pack for your own project, see the [Set up a new project](https://canonical-starter-pack.readthedocs-hosted.com/stable/tutorial/set-up/) guide in the official documentation.
 
-The file `test-starter-pack.yml` tests the functionality of the starter pack project.
+## Requirements and limitations
 
-## Contributing
+<!--Local build requirements - any linux OS? python preinstalled? I feel like this should be clarified in the section above though-->
 
-We welcome contributions to this project! If you have suggestions, bug fixes, or improvements, please open an issue or submit a pull request.
+The Starter Pack is designed for projects hosted on GitHub. This is necessary to run the automatic checks in .github/workflows, and to publish your documentation on Read The Docs.
 
-Please read and sign our [Contributor Licence Agreement (CLA)] before submitting any changes. The agreement grants Canonical permission to use your contributions. The author of a change remains the copyright owner of their code (no copyright assignment occurs).
+If you have a project that is hosted on a different versioning platform, like Launchpad, [reach out to us](#reach-out).
+
+## Community and support
+
+The Canonical Sphinx Starter pack is an open-source project that warmly welcomes community involvement.
+
+If you’re new to the community, make sure to read through the [Ubuntu Code of Conduct](https://ubuntu.com/community/code-of-conduct) first.
+
+### Reach out
+
+* Report an issue or make a suggestion via [GitHub](https://github.com/canonical/sphinx-docs-starter-pack/issues)
+* Come chat with the Canonical Documentation team in our [public Matrix channel](https://matrix.to/#/#documentation:ubuntu.com)
+
+### Contribute
+
+The Starter Pack provides a shared foundation for Sphinx documentation projects, and contributions help improve the documentation of all its users.
+
+* See [CONTRIBUTING.md](CONTRIBUTING.md) for more details about contributing to development or documentation
+* Check [open issues](https://github.com/canonical/sphinx-docs-starter-pack/issues)
+
+<!--
+Tempted to remove this, since it's clearly explained in CONTRIBUTING.md
+
+Please read and sign our [Contributor Licence Agreement (CLA)] before submitting any changes. The agreement grants Canonical permission to use your contributions. The author of a change remains the copyright owner of their code (no copyright assignment occurs).-->
 
 <!--Links-->