Update README

Author: penelopeysm

README.md

@@ -1,7 +1,9 @@
 # Documentation and Tutorials for Turing.jl
 
-This repository is part of [Turing.jl's](https://turinglang.org/) website (i.e. `https://turinglang.org/docs/`). It contains the Turing.jl documentation and tutorials. 
-- The `main` branch contains the quarto source 
+This repository hosts the code for the main Turing.jl documentation `https://turinglang.org/docs/`.
+It contains the Turing.jl documentation and tutorials. 
+
+- The `main` branch contains the Quarto source.
 - The `gh-pages` branch contains the `html` version of these documents compiled from the `main` branch.
 
 ## Local development
@@ -29,7 +31,10 @@ Once you have Quarto installed, you can follow these steps:
     julia --project=. -e 'using Pkg; Pkg.instantiate()'
     ```
 
-4. Preview the website using Quarto Preview:
+4. Preview the website using Quarto.
+
+   > [!WARNING]  
+   > This will take a _very_ long time, as it will build every tutorial from scratch. See below for ways to speed this up.
 
     ```bash
     quarto preview
@@ -54,18 +59,29 @@ Once you have Quarto installed, you can follow these steps:
 
     Then, navigate to http://localhost:8000/ in your web browser.
 
-    Note that rendering the entire documentation site can take a long time (usually multiple hours).
-    If you wish to speed up local rendering, there are two options available:
+## Faster rendering
+
+Note that rendering the entire documentation site can take a long time (usually multiple hours).
+If you wish to speed up local rendering, there are two options available:
+
+1. Render a single tutorial or `qmd` file without compiling the entire site.
+   To do this, pass the `qmd` file as an argument to `quarto render`:
+
+   ```
+   quarto render path/to/index.qmd
+   ```
 
-    - Download the most recent `_freeze` folder from the [GitHub releases of this repo](https://github.com/turinglang/docs/releases), and place it in the root of the project.
-      This will allow Quarto to reuse the outputs of previous computations for any files which have not been changed since that `_freeze` folder was created.
+   (Note that `quarto preview` does not support this single-file rendering.)
 
-    - Alternatively, render a single tutorial or `qmd` file without compiling the entire site.
-      To do this, pass the `qmd` file as an argument to `quarto render`:
+2. Download the most recent `_freeze` folder from the [GitHub releases of this repo](https://github.com/turinglang/docs/releases), and place it in the root of the project.
+   The `_freeze` folder stores the cached outputs from a previous build of the documentation.
+   If it is present, Quarto will reuse the outputs of previous computations for any files for which the source is unchanged.
 
-      ```
-      quarto render path/to/index.qmd
-      ```
+   Note that the validity of a `_freeze` folder depends on the Julia environment that it was created with, because different package versions may lead to different outputs.
+   In the GitHub release, the `Manifest.toml` is also provided, and you should also download this and place it in the root directory of the docs.
+   
+   If there isn't a suitably up-to-date `_freeze` folder in the releases, you can generate a new one by [triggering a run for the `create_release.yml` workflow](https://github.com/TuringLang/docs/actions/workflows/create_release.yml).
+   (You will need to have the appropriate permissions; please create an issue if you need help with this.)
 
 ## Troubleshooting build issues