Describe how to contribute to docs

developers/contributing/index.qmd

@@ -19,14 +19,37 @@ If you are new to open source software, please see [GitHub's introduction](https
 
 ### Documentation
 
+#### Where is Turing's documentation?
+
 Each of the packages in the Turing ecosystem (see [Libraries](/library)) has its own documentation, which is typically found in the `docs` folder of the corresponding package.
 For example, the source code for DynamicPPL's documentation can be found in [its repository](https://github.com/TuringLang/DynamicPPL.jl).
 
-The documentation for Turing.jl itself consists of the tutorials that you see on this website, and is built from the separate [`docs` repository](https://github.com/TuringLang/docs).
-None of the documentation is generated from the [main Turing.jl repository](https://github.com/TuringLang/Turing.jl); in particular, the API that Turing exports does not currently form part of the documentation.
+On top of the library-specific documentation, we also have a general documentation repository, which is what builds the website you are currently reading!
+Anything that appears in `turinglang.org/docs` is built from the [`docs` repository](https://github.com/TuringLang/docs).
 
 Other sections of the website (anything that isn't a package, or a tutorial) – for example, the list of libraries – is built from the [`turinglang.github.io` repository](https://github.com/TuringLang/turinglang.github.io).
 
+In general, we prefer documentation to be written on the `TuringLang/docs` repository.
+This is because it is more easily discoverable for users via the search bar and sidebar.
+Documentation written on the individual package repositories can be found via the main site's search bar (due to a GitHub workflow that scrapes all the packages' contents and indexes them here), but once you navigate to a package's documentation, you cannot then use the sidebar to come back to the main documentation site.
+
+#### Documenting unreleased features
+
+There are sometimes cases where it is not possible to add docs to the `TuringLang/docs` repository.
+In particular, because the `TuringLang/docs` repo builds from a released version of Turing and all its dependencies, new features in unreleased versions cannot be documented here.
+However, it's always better to document things as you go along rather than to wait for a release and then play catch-up!
+In such instances, we recommend first adding documentation to the relevant package's `docs` folder (using Documenter.jl as usual), and later copying it over to the main `TuringLang/docs` repository (adjusting for the Quarto format) once the new version is released.
+Note that because the `TuringLang/docs` repository is tied to a specific version of Turing.jl, if you have updated the documentation for a new dependency of Turing (e.g. DynamicPPL or Bijectors), you also need to ensure that there is a version of Turing.jl that is compatible with that new version.
+
+#### Environments
+
+The `TuringLang/docs` repository is built from a single Manifest file, which contains a pinned version of Turing.jl.
+All notebooks are run with the same environment, which ensures consistency across the documentation site.
+
+In general, you should **not** add new packages to this environment which **depend** on Turing (i.e., reverse dependencies of Turing), or packages that have Turing extensions.
+The reason for this is because such packages will have compatibility bounds on Turing.
+Thus, we will be unable to update the docs to use the newest Turing version, until and unless those packages also update their compatibility bounds.
+
 ### Tests
 
 Turing, like most software libraries, has a test suite. You can run the whole suite by running `julia --project=.` from the root of the Turing repository, and then running
@@ -190,4 +213,4 @@ When adhering to the Blue style, it's important to realise that these are guidel
 
 > A style guide is about consistency. Consistency with this style guide is important. Consistency within a project is more important. Consistency within one module or function is most important.
 
-> But most importantly: know when to be inconsistent – sometimes the style guide just doesn't apply. When in doubt, use your best judgment. Look at other examples and decide what looks best. And don't hesitate to ask!
+> But most importantly: know when to be inconsistent – sometimes the style guide just doesn't apply. When in doubt, use your best judgment. Look at other examples and decide what looks best. And don't hesitate to ask!