add instructions for contributing to user docs

book/_toc.yml

@@ -7,8 +7,8 @@ parts:
 
   - caption: "Docs"
     chapters:
-      - file: docs/intro
-        title: Introduction
+      - file: docs/user-documentation
+      - file: docs/developer-documentation
 
   - caption: "Plugins"
     chapters:

book/docs/developer-documentation.md

@@ -0,0 +1 @@
+# Contributing to the QIIME 2 developer documentation

book/docs/user-documentation.md

@@ -0,0 +1,60 @@
+# Contributing to the QIIME 2 user documentation
+
+As of the time of this writing (12 January 2023) the QIIME 2 user documentation is in a state of transition.
+This document covers how to contribute to the current user documentation (https://docs.qiime2.org), and presents some ideas about where we're planning to go with the user documentation in the future.
+
+## Contributing to the current user documentation
+
+```{warning}
+These instructions are a little sparse at the moment and don't cover things like working on your own fork or branch of the documentation. We do recommend forking and working on your own change-specific branch.
+```
+
+First, install the most recent release version of the QIIME 2 Amplicon Distribution, or [create a QIIME 2 Amplicon Distribution development environment](setup-dev-environment). Switch to that new environment.
+
+Then, clone the QIIME 2 User documentation repository and install its requirements.
+
+```bash
+git clone https://github.com/qiime2/docs.git
+cd docs
+pip install -r requirements.txt
+```
+
+Build the documentation in `preview` mode to confirm that the build works before making your changes.
+
+```{note}
+Building the documentation in `preview` mode will avoid running all of the QIIME 2 steps covered in the tutorials during the build of the documentation, which will be vastly faster than doing a complete build (i.e., `make html`) of the documentation.
+```
+
+```bash
+make preview
+```
+
+Make your edits, and re-build and view them. Iterate on this process until you're done.
+
+```bash
+make preview
+cd build/preview && python -m http.server ; cd -
+```
+
+The above command will launch a web server on your computer. Open http://localhost:8000/ in your browser to view the documentation as hosted on that local web server.
+
+When you're ready, submit a pull request in the usual way.
+
+## Plans for refactoring of user documentation
+
+We are moving from a single source of documentation (the current content at https://docs.qiime2.org) to resources for **cross-distribution QIIME 2 documentation**, **within-distribution QIIME 2 reference material**, and **data set specific usage documentation**.
+
+We expect that the **cross-distribution user documentation** will cover topics including:
+- building and use a cache, which will expand on the [content here](https://forum.qiime2.org/t/qiime-2-2022-11-is-now-available/25074#artifact-cachehttpsdevqiime2orglatestapi-referencecache-3)
+- parallel support
+- provenance replay/viewing, which will expand on the [content here](https://forum.qiime2.org/t/provenance-replay-beta-release-and-tutorial/23279)
+- using the interfaces
+- recycling old results
+- installing old versions of QIIME 2 (why, why not, and how)
+- discussion of distributions (why are there multiple? how to deal with that)
+- importing/exporting
+- viewing .qzvs
+
+**Distribution specific reference material** will likely be the equivalent of our [current plugin/action pages](https://docs.qiime2.org/2023.9/plugins/). These will render all usage examples associated with actions as well, to avoid the need for things like the ["filtering tutorial"](https://docs.qiime2.org/2023.9/tutorials/filtering/) (which isn't really a tutorial, but rather a list of different approaches for filtering data). Ideally generation of distribution-specific reference documentation will be fully automated, such that these docs can be built from any QIIME 2 environment using the `PluginManager`.
+
+**Usage tutorials**, like the [Moving Pictures tutorial](https://docs.qiime2.org/2023.9/tutorials/moving-pictures-usage/), will be dataset specific and may cross distributions (like the [Cancer Microbiome Intervention Tutorial](https://docs.qiime2.org/jupyterbooks/cancer-microbiome-intervention-tutorial/)). This will facilitate the transition from replayed provenance to tutorial, ideally helping to blur the line between replayed provenance and a tutorial over time. To support this, we will likely add a usage driver that generates usage driver source code (for example, select `View Source (qiime2.sdk)` from a [multi-interface tutorial](https://docs.qiime2.org/2023.9/tutorials/moving-pictures-usage/), so this can template documentation.

book/plugins/how-to-guides/set-up-development-environment.md

@@ -1,4 +1,4 @@
-
+(setup-dev-environment)=
 # Set up your development environment
 
 This how-to guide describes how to install and set up a QIIME 2 development environment.