transfer content based on re-assessment of where it belongs (#107)

book/_toc.yml

@@ -22,6 +22,10 @@ parts:
         - file: plugins/how-to-guides/intro
           sections:
             - file: plugins/how-to-guides/set-up-development-environment
+            - file: plugins/how-to-guides/distribute-on-gh
+            - file: plugins/how-to-guides/support-your-users
+            - file: plugins/how-to-guides/maximize-compatibility
+            - file: plugins/how-to-guides/publicize
             - file: plugins/how-to-guides/register-a-plugin
             - file: plugins/how-to-guides/create-register-method
             - file: plugins/how-to-guides/create-register-visualizer
@@ -32,7 +36,7 @@ parts:
             - file: plugins/how-to-guides/use-metadata
             - file: plugins/how-to-guides/test-plugins
             - file: plugins/how-to-guides/usage-examples
-            - file: plugins/how-to-guides/format-validation-levels.md
+            - file: plugins/how-to-guides/format-validation-levels
         - file: plugins/explanations/intro
           sections:
             - file: plugins/explanations/actions
@@ -85,15 +89,6 @@ parts:
   - caption: "Continuous Integration 🛠️"
     chapters:
       - file: ci/intro
-        sections:
-        - file: ci/tutorials/intro
-          sections:
-          - file: ci/tutorials/distribute-on-gh
-        - file: ci/how-to-guides/intro
-          sections:
-          - file: ci/how-to-guides/support-your-users
-          - file: ci/how-to-guides/publicize
-          - file: ci/how-to-guides/maximize-compatibility
 
   - caption: "Back Matter 🗂️"
     chapters:

book/ci/intro.md

@@ -2,19 +2,16 @@
 # Distribution Development
 
 ```{note}
-This Part of DWQ2 is in early development.
+This Part of DWQ2 is in early development, and currently provides references to relevant content in other Parts of *Developing with QIIME 2*.
 We're open to feedback on the ideas presented here, and some technical details may change as the ideas develop.
 ```
 
 You don't need approval from existing QIIME 2 developers to create and distribute your own tools, such as plugins or interfaces, that build on QIIME 2.
-This is the beauty of [plugin-based, interface-agnostic architecture](q2-architecture-overview): new functionality can be introduced by anyone, removing bottlenecks or gatekeepers between developers and users.
+This is the beauty of [plugin-based, interface-agnostic architecture](q2-architecture-overview): new functionality or new ways to use that functionality can be introduced by anyone, removing bottlenecks or gatekeepers between developers and users.
 Customized QIIME 2 distributions can also be created and shared by anyone.
 
 As of this writing (23 April 2024) we are redesigning our approach to helping you share and promote your QIIME 2-based tools.
-[](share-on-github) provides an example of how you can currently share your tools with users, and we are actively working to expand that functionality to make it more useful for developers and users.
-We also discuss more general ideas on sharing QIIME 2-based tools in [](ci-how-to-publicize).
+[](share-on-github) provides an example of how you can currently share your plugin with users, and we are actively working to expand that functionality to make it more useful for developers and users.
+We also discuss more general ideas on sharing QIIME 2-based tools in [](plugin-how-to-publicize).
 
 As our support in this area improves, this Part of *Developing with QIIME 2* will be expanded to describe new functionality.
-
-```{tableofcontents}
-```

book/ci/tutorials/distribute-on-gh.md → book/plugins/how-to-guides/distribute-on-gh.md

@@ -1,5 +1,5 @@
 (share-on-github)=
-# Distributing plugins on GitHub
+# Distribute plugins on GitHub
 
 GitHub is a straight-forward way to share your QIIME 2 plugin.
 This tutorial will walk you through creating a QIIME 2 plugin from template, and then sharing it with installation instructions on GitHub.
@@ -76,6 +76,5 @@ Here are some tips related to updating the installation instructions for your pl
 - Be sure to update the `README.md` if you introduce any new constraints (e.g., that your plugin can only be installed on Linux).
   It's fine to do that, but you should let your users know so they don't get grumpy about your plugin.
 
-If you're ready to start getting users, the next steps are helping prospective users discover your plugin, and supporting them as they learn to use it.
-We have some suggestions on those topics and others in this Part's [](ci-how-to-intro).
+If you're ready to start getting users, the next steps are [helping prospective users discover your plugin](plugin-how-to-publicize), and [supporting them as they use it](plugin-how-to-support-your-users).
 

book/ci/how-to-guides/maximize-compatibility.md → book/plugins/how-to-guides/maximize-compatibility.md

@@ -1,4 +1,4 @@
-(ci-how-to-maximize-compatibility)=
+(plugin-how-to-maximize-compatibility)=
 # Maximize compatibility between your plugin(s) and existing QIIME 2 distribution(s)
 
 You can build your QIIME 2 tools in your own way.
@@ -11,7 +11,7 @@ A complete list of artifact classes and formats available in a deployment of QII
 (Some are missing documentation - we'd [love your help addressing that](https://github.com/caporaso-lab/developing-with-qiime2/issues/97).)
 If you do need to create new artifact classes, you can add these in your own plugin(s).
 
-The Caporaso Lab is not taking on new responsibility for distributing plugins right now (i.e., integrating them in the distributions they develop and maintain), but we are curently (23 April 2024) developing new mechanisms for helping you share your plugin or other tools (see [](ci-how-to-publicize)) that will ultimately replace the [QIIME 2 Library](https://library.qiime2.org).
+The Caporaso Lab is not taking on new responsibility for distributing plugins right now (i.e., integrating them in the distributions they develop and maintain), but we are currently (23 April 2024) developing new mechanisms for helping you share your plugin or other tools (see [](plugin-how-to-publicize)) that will ultimately replace the [QIIME 2 Library](https://library.qiime2.org).
 
 You can consider the existing distributions to be foundations that you can build on, or you can create and distribute your own conda metapackages.
 Some guidance on each of these approaches:

book/ci/how-to-guides/publicize.md → book/plugins/how-to-guides/publicize.md

@@ -1,7 +1,7 @@
-(ci-how-to-publicize)=
-# Publicize your QIIME 2 tools
+(plugin-how-to-publicize)=
+# Publicize your QIIME 2 plugins (or other QIIME 2-based tools)
 
-If you want others to use your QIIME 2 tools, you have to market them.
+If you want others to use your QIIME 2-based tools, such as plugins, you have to market them.
 Ultimately that's your responsibility - **you** built it, **you** know it, **you're** proud of it, so **you need to promote it**.
 
 Here are some ideas on how to market your tools.

book/ci/how-to-guides/support-your-users.md → book/plugins/how-to-guides/support-your-users.md

@@ -1,4 +1,4 @@
-(ci-how-to-support-your-users)=
+(plugin-how-to-support-your-users)=
 # Provide technical support for your users
 
 You are free to have your users request help on the [QIIME 2 Forum](https://forum.qiime2.org) for your QIIME 2-based tools.