User documentation

As of the time of this writing (22 May 2025) the QIIME 2 user documentation is in a state of transition. Most new documentation is currently being built using Jupyter Book 2.

User documentation refactor

We have recently (as of 22 May 2025) moved from a single source of documentation (previously at https://docs.qiime2.org) to resources for cross-distribution QIIME 2 documentation, within-distribution QIIME 2 documentation, plugin-specific documentation, and data set specific usage documentation.

The primary sources of cross-distribution user documentation are Using QIIME 2 and Developing with QIIME 2. These cover things (or will cover things) like:

• developing QIIME 2 plugins and interfaces

• building and use an artifact cache

• parallel analysis support

• provenance replay/viewing, which will expand on the content here

• using the interfaces

• recycling results from failed runs

• 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 QIIME 2 Visualizations

Distribution specific documentation will cover pre-built distributions of QIIME 2, including:

• the amplicon distribution documentation

• MOSHPIT documentation (MOSHPIT was previously referred to as the metagenome distribution)

Data-set specific tutorials, like the Moving Pictures tutorial or the more recent gut-to-soil microbiome axis tutorial, will be dataset specific and may cross distributions (like the 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 to Provenance Replay that generates usage driver source code (for example, select View Source (qiime2.sdk) from a multi-interface tutorial like gut-to-soil, so Provenance Replay can template documentation.

Plugin-specific documentation, like the q2-boots documentation.

The use of Jupyter Book 2 allows us to re-use content as relevant across these resources.

If you’d like to contribute documentation, this should be done in the context of a specific documentation project.