The QIIME 2 Library “Stacks”
Hello QIIME 2 user community! You may have noticed that our documentation is starting to look different. This article is a quick description of what's changing and why.
Restructured documentation
As the collection of distributions and plugins grows, it's become necessary for us to split our documentation into a few pieces.
- We have distribution documentation, such as the new QIIME 2 "amplicon distribution" documentation and the MOSHPIT (formerly known as the "metagenome distribution") documentation. These are oriented toward end users, and cover distributions that provide many related plugins. Most users start with one of these documentation sources. The old QIIME 2 user documentation was most similar to this, in that it described how to use QIIME 2 to analyze microbiome amplicon data.
- There is also plugin documentation, such as the q2-fmt and genome-sampler documentation. These are similar to distribution documentation, but cover plugins that are distributed independently of distributions.
- We also now have QIIME 2 Framework (Q2F) documentation, including Developing with QIIME 2 and Using QIIME 2. These are oriented toward developers and power users, respectively, and provide information that is relevant to anyone using tools that are built on Q2F (which includes the distributions and plugins mentioned above). [1]
- Finally we have dataset-focused tutorials, like the new gut-to-soil microbiome axis tutorial (as well as the classic “Moving Pictures” tutorial). You’ll most often discover them embedded in other documentation rather than navigating to them directly. Ultimately, some of these will cross distributions providing multi-omics educational content.
We recognize that there are now a lot of different documentation sources, but that's because Q2F is now supporting diverse biological data science tools and the applications are only expanding. The central location for discovery of these documentation sites is the new QIIME 2 Library “Stacks” [2], and you’ll find documentation organized under the categories listed above.
Transition to Jupyter Book 2
We're also in the process of transitioning our documentation from the Sphinx documentation engine (e.g., this is how we built the old QIIME 2 user documentation) and Jupyter Book (e.g., as we're still using for Developing with QIIME 2 to Jupyter Book 2 (JB2). We're excited about a few things with JB2.
First, all content is written in MyST Markdown, which is convenient to write and the MyST ecosystem provides diverse formatting options.
Next, JB2 makes it convenient to reuse content, which we think will be particularly helpful for the Q2F ecosystem. For example, if we write a general explanation such as a discussion of how to create and use an Artifact Cache for Using QIIME 2, we can embed that content in other places where it may be relevant, such as the MOSHPIT documentation. We think this is very well-suited to the nature of the Q2F ecosystem where some content is general across all distributions and some is distribution specific. In other words, it helps us keep our documentation DRY, and therefore helps us ensure you're not learning from outdated content.
Finally, it's straightforward to write JB2 plugins, and we've done this to automate the generation of our plugin index pages (for example, this one). Based on our website analytics, this was some of the most frequently accessed content from the old amplicon documentation. You can now expect to see these for other distributions and in plugin-specific documentation (e.g., the genome-sampler plugin index and the q2-fmt plugin index). Plugin developers: if you're interested in building these plugin indices automatically for your tools, that's now possible! We're working on some new content to describe how to achieve that, but in the meantime feel free to reach out (e.g., Developer Discussion on the QIIME 2 Forum is a great place for discussion about this).
Transition to ReadTheDocs
We're also transitioning from hosting our documentation through our custom build system to hosting on ReadTheDocs. The most noticeable change here will be that there is more explicit versioning of our documentation, which will make it easier to browse documentation associated with different versions of our tools. This should also help with indexing of our documentation by search engines, which has historically been an issue for the old user documentation.
We hope you enjoy all of the new changes to our documentation ecosystem. Our goal is to leverage all of this to help you better understand how to apply our tools. If you have any feedback about how we can do that, or requests for specific documentation, we're always open to that feedback. Reach out on the QIIME 2 Forum if you have ideas you'd like to share!
To reduce confusion between what is "QIIME 2" (the microbiome analysis tool) and what is the "QIIME 2 Framework" (the underlying functionality that powers QIIME 2, MOSHPIT, and stand-alone plugins like q2-micom, q2-picrust2, and q2-metnet) we are beginning work on a rebrand of the QIIME 2 Framework (i.e., the code at GitHub - qiime2/qiime2: Source for the QIIME 2 Framework (Q2F).). That change will be the subject of an upcoming News post on the QIIME 2 Forum. If you're a user of QIIME 2 or MOSHPIT, or a developer or user of plugins, this change will not impact you in any way: those names aren’t changing, import paths remain backward compatible, and the tools you're used to using will continue to work in the same way. More soon! ↩︎