docs: preparing more skeleton, updating /docs page

Author: dbirman

docs/source/acquire_upload.md

@@ -8,6 +8,8 @@
 
 [Upload my data assets](acquire_upload/upload.md) to the Cloud.
 
+[Process my data assets](acquire_upload/processing.md) using our per-modality standard pipelines.
+
 ```{toctree}
 :hidden:
 

docs/source/acquire_upload/on_rig.md

@@ -1,3 +1,9 @@
 # On rig
 
-[TODO]
+During data acquisition you are responsible for running version-controlled acquisition software and ensuring your data files are organized according to a standardized system. Metadata generated during acquisition captures **what data** should appear in the final NWB files after processing, as well as **what manipulations** were performed (both behavioral stimuli and any procedures).
+
+## Data file standards
+
+Raw data assets should be organized by modality.
+
+## 

docs/source/acquire_upload/processing.md

@@ -0,0 +1,2 @@
+# Per-modality pipelines
+

docs/source/docs.md

@@ -1,26 +1,29 @@
-# Documentation Guidelines
+# Documentation guidelines
 
 ## What 
 
-As a developer you are responsible for providing four kinds of documentation: **tutorials** for beginners learning how to use a tool, **how-to guides** for achieving specific goals, technical **reference** for understanding software, and **explanation** for understanding why tools were built the way they are.
+As a developer you are responsible for providing four kinds of documentation: **tutorials** for beginners learning how to use a tool, **how-to guides** for achieving specific goals, technical **reference** for understanding software, and **explanation** for understanding why tools were built the way they are. Our documentation is organized according to the [diataxis](https://diataxis.fr/) framework.
 
+At a minimum, you must provide a technical **reference** in the `README.md` file in every GitHub repository that you maintain and update the standard headers in the [aind-library-template](https://github.com/AllenNeuralDynamics/aind-library-template): Usage, Level of Support, Installation.
 
+All packages should include:
 
-## Where
+1. A **tutorial** aimed at total beginners using your package that walks them through a basic example.
+2. **How-to guides** for specific use-cases of your package. Note that AIND-specific use cases should be documented in [aind-software-docs](https://github.com/AllenNeuralDynamics/aind-software-docs).
 
-| Location | Type | User | Details |
-|----------|------|------|---------|
-| [aind-software-docs](https://github.com/AllenNeuralDynamics/aind-software-docs)  | Tutorials | New users | User stories, tutorials, and links to technical documentation |
-| Documentation pages for your repository | How-to Guides | Technical users | Technical details about a library |
-| Documentation pages for your repository | Reference | Developers | Developer documentation, contributing guidelines, and deployment details |
-| Talks, project proposals, white papers, documentation pages for your repository | Explanation | Developers | Why we did things the way we did |
+For packages that are fully released you should also add:
 
-## How
+3. **Technical reference**, generally auto-generated library or API docs.
+4. **Explanation** of technical or philosophical decisions made during development. Links to a preprint or paper can often take the place of an explanation section.
+
+As an example, on the [aind-data-schema documentation](https://aind-data-schema.readthedocs.io/en/latest/example_workflow/example_workflow.html) the [Generating metadata](https://aind-data-schema.readthedocs.io/en/latest/example_workflow/example_workflow.html) section is a tutorial, the [Core and Component Schemas](https://aind-data-schema.readthedocs.io/en/latest/data_description.html) pages are reference, and the [Philosophy](https://aind-data-schema.readthedocs.io/en/latest/general.html) sections provide some explanation of *why* certain decisions were made.
 
-You can contribute directly to this repository with a pull request and review.
+## How
 
 Libraries built using the `aind-library-template` automatically have a read-the-docs documentation built-in. You can write `.rst` files or add the `myst-parser` package and write `.md` files. You can deploy your documentation directly on the [read-the-docs](https://readthedocs.org).
 
+You can contribute updates and how-to guides for your tools directly to this repository with a pull request and review.
+
 ## Why
 
-[Diataxis](https://diataxis.fr/)
+Software engineer at AIND has grown to a scale where a central entry-point for users should make it far easier to find and learn about our tools. Across packages we are also taking a variety of approaches to documentation, iteratively moving toward a more standardized "feel" in our documentation will reduce the overhead for users who are only rarely interacting with documentation during their scientific work.

docs/source/explore_analyze/analysis_framework.md

@@ -0,0 +1,3 @@
+# Analysis framework
+
+The [Analysis Framework](https://codeocean.allenneuraldynamics.org/capsule/3390834/tree/v1) is a Code Ocean pipeline that provides a template for facilitating large-scale analysis for data assets. Use the analysis framework anytime your analysis capsule(s) need to be run at scale on many individual data assets.

docs/source/index.md

@@ -10,6 +10,8 @@
 
 [Propose a project](proposals.md) with scientific computing support.
 
+[Publish and share](share.md) my data with external users.
+
 ## I need to report an...
 
 [Issue with scientific computing software](https://github.com/AllenNeuralDynamics/aind-scientific-computing/).
@@ -24,6 +26,10 @@ Follow these links to request access to:
 - [GitHub Copilot](https://alleninstitute.service-now.com/sp?id=sc_cat_item&sys_id=83bc1726477aa91032b789b5536d430e&referrer=popular_items) - via ServiceNow
 - [VAST /allen/aind/scratch and /allen/aind/stage](https://alleninstitute.service-now.com/sp?id=sc_cat_item&sys_id=83bc1726477aa91032b789b5536d430e&referrer=popular_items) - via ServiceNow
 
+## I want to learn about...
+
+[Data governance](phil)
+
 ```{toctree}
 :maxdepth: 2
 :hidden:
@@ -32,6 +38,7 @@ Follow these links to request access to:
 acquire_upload
 explore_analyze
 proposals
+share
 
 ```
 
@@ -40,6 +47,16 @@ proposals
 :hidden:
 :caption: Resources
 
+docs
 core_services
 
 ```
+
+```{toctree}
+:maxdepth: 1
+:hidden:
+:caption: Philosophy
+
+philosophy
+
+```

docs/source/philosophy.md

@@ -0,0 +1 @@
+# Data philosophy at AIND

docs/source/share.md

@@ -0,0 +1,2 @@
+# Publish and share
+