diff --git a/book/intro.md b/book/intro.md index 44a1cb6..58197fa 100644 --- a/book/intro.md +++ b/book/intro.md @@ -1,11 +1,11 @@ # *Using QIIME 2* -**Make QIIME 2 work for you.** +**Your guide to becoming a QIIME 2 Framework power user.** ```{admonition} Development status of this content :class: note *Using QIIME 2* is in an early stage of development, and as a result the documentation at https://docs.qiime2.org is still an important source of information for learning to use QIIME 2. -Over the next few months (as of 10 October 2024), existing content will be migrated and new content will developed. +Over the next few months (as of 17 January 2025), existing content will be migrated and new content will developed. Ultimately https://docs.qiime2.org will be retired. While *Using QIIME 2* is in development, some URLs may change. @@ -14,11 +14,11 @@ The canonical URL for this project is https://use.qiime2.org. ## Goals and development plan for *Using QIIME 2* -As the ecosystem of QIIME 2 {term}`distributions ` and {term}`plugins ` continues to grow, it has become necessary to make a split in the documentation between general-purpose information that describes how to use QIIME 2 itself (i.e., "the QIIME 2 framework" 🌳), and how to apply the tools it supports to achieve your data analysis goals. +As the ecosystem of QIIME 2 {term}`distributions ` and {term}`plugins ` continues to grow, it has become necessary to make a split in the documentation between general-purpose information that describes how to use QIIME 2 itself **(i.e., "the QIIME 2 framework" 🌳)**, and how to apply the tools it supports to achieve your data analysis goals. We know that you're interested in QIIME 2 primarily for the latter -- to achieve specific analysis goals related to microbiome data science -- so our goal is that *Using QIIME 2* serves primarily as a source for you to refer to when you need to accomplish specific tasks that are general to using the system. -That includes things like [using `Artifacts` as metadata](metadata-merge), replaying provenance[^replaying-provenance-issue], and [configuring your parallel computing environment](parallel-configuration). +That includes things like [using `Artifacts` as metadata](metadata-merge), replaying provenance[^replaying-provenance-issue], [creating and using an artifact cache](artifact-cache-tutorial) and [configuring your parallel computing environment](parallel-configuration). It will also include explanations that can help you understand the system when you want to go deeper, including things like what QIIME 2 {term}`Artifacts ` (e.g., {term}`.qza ` files) and {term}`Visualizations ` (e.g., {term}`.qzv ` files) are[^result-explanation-issue], and why you need to import your data into `Artifacts` before using QIIME 2[^importing-explanation-issue]. -Generally speaking, **understanding these topics will help you understand what you're doing and empower you to become a QIIME 2 power user, but they aren't strictly necessary to perform simple data analysis.** +Generally speaking, **understanding these topics will help you understand what you're doing and empower you to become a QIIME 2 Framework power user, but they aren't strictly necessary to perform simple data analysis.** In addition to *Using QIIME 2*, we are building distribution-specific and plugin-specific documentation. **These will be designed to quickly get you started with performing your first data analysis with QIIME 2,** and will fall into a few categories. @@ -26,12 +26,12 @@ In addition to *Using QIIME 2*, we are building distribution-specific and plugin ### Distribution-specific documentation The "old" user documentation at https://docs.qiime2.org serves this purpose for the *amplicon distribution*. -For example, you can start there to get instructions on how to [install QIIME 2](https://docs.qiime2.org/2024.5/install/), use it to carry out an [analysis of microbiome amplicon data](https://docs.qiime2.org/2024.5/tutorials/moving-pictures-usage/), and [see a reference](https://docs.qiime2.org/2024.5/plugins/) of the {term}`plugins ` and {term}`actions ` that are included in the *amplicon distribution*. +For example, you can start there to get instructions on how to [install QIIME 2](https://docs.qiime2.org/2024.10/install/), use it to carry out an [analysis of microbiome amplicon data](https://docs.qiime2.org/2024.10/tutorials/moving-pictures-usage/), and [see a reference](https://docs.qiime2.org/2024.10/plugins/) of the {term}`plugins ` and {term}`actions ` that are included in the *amplicon distribution*. That user documentation predates the diverse distributions and plugins that now exist in the ecosystem - it therefore mixes distribution-specific information with the general purpose information that is currently being transitioned to *Using QIIME 2*. ### Plugin-specific documentation -Stand-alone plugins (i.e., those not included in existing distributions), like [q2-boots](https://github.com/caporaso-lab/q2-boots), will provide their own documentation linked from the new QIIME 2 Library[^new-library-not-live]. +Stand-alone plugins (i.e., those not included in existing distributions), like [q2-boots](https://github.com/caporaso-lab/q2-boots), will provide their own documentation linked from [the new QIIME 2 Library](https://library.qiime2.org)[^new-library-wip]. For now, you can refer to the [q2-boots documentation here](https://q2-boots.readthedocs.io/en/latest/), as an example of where we're going. ### Data-set specific documentation @@ -94,6 +94,7 @@ Initial support for the development of QIIME 2 was provided through a [grant](ht

Using QIIME 2 led by Greg Caporaso is licensed under CC BY-NC-ND 4.0 .

[^replaying-provenance-issue]: See [here](https://github.com/caporaso-lab/using-qiime2/issues/13). - [^new-library-not-live]: The new QIIME 2 Library is not yet live, but will be soon (as of 10 October 2024). - [^result-explanation-issue]: See [here](https://github.com/caporaso-lab/using-qiime2/issues/11). - [^importing-explanation-issue]: See [here](https://github.com/caporaso-lab/using-qiime2/issues/12). \ No newline at end of file +[^new-library-wip]: The new QIIME 2 Library is in the early stages of development (as of 17 January 2025) - a lot of exciting new functionality for both users and developers is currently in progress! +For the time-being, you can still find the old QIIME 2 Library at https://old-library.qiime2.org. +[^result-explanation-issue]: See [here](https://github.com/caporaso-lab/using-qiime2/issues/11). +[^importing-explanation-issue]: See [here](https://github.com/caporaso-lab/using-qiime2/issues/12). \ No newline at end of file diff --git a/book/tutorials/use-the-artifact-cache.md b/book/tutorials/use-the-artifact-cache.md index ca93995..6e0ef15 100644 --- a/book/tutorials/use-the-artifact-cache.md +++ b/book/tutorials/use-the-artifact-cache.md @@ -1,7 +1,7 @@ (artifact-cache-tutorial)= # Using an Artifact Cache -The artifact cache allows users to have finer control over where and how QIIME 2 {term}`Results ` are stored on disk. +An artifact cache allows users to have finer control over where and how QIIME 2 {term}`Results ` are stored on disk. Artifact caches serve two primary purposes: 1. Providing the user with control over where QIIME 2 stores its working (temporary) files.