separating longer format tutorials to examples.

docs/index.md

@@ -5,21 +5,22 @@
 
 MPoL is a [PyTorch](https://pytorch.org/) *library* built for Regularized Maximum Likelihood (RML) imaging and Bayesian Inference with datasets from interferometers like the Atacama Large Millimeter/Submillimeter Array ([ALMA](https://www.almaobservatory.org/en/home/)) and the Karl G. Jansky Very Large Array ([VLA](https://public.nrao.edu/telescopes/vla/)). 
 
-As a PyTorch *library*, MPoL is designed expecting that the user will write Python code that uses MPoL primitives as building blocks to solve their interferometric imaging workflow, much the same way the artificial intelligence community uses PyTorch layers to implement new neural network architectures (for [example](https://github.com/pytorch/examples)). You will find MPoL easiest to use if you emulate PyTorch customs and idioms, e.g., feed-forward neural networks, data storage, GPU acceleration, and train/test optimization loops. Therefore, a basic familiarity with PyTorch is considered a prerequisite for MPoL.
+As a PyTorch *library*, MPoL expects that the user will write Python code to link MPoL primitives as building blocks to solve their interferometric imaging workflow, much the same way the artificial intelligence community uses PyTorch layers to build new neural network architectures (for [example](https://github.com/pytorch/examples)). You will find MPoL easiest to use if you emulate PyTorch customs and idioms, e.g., feed-forward neural networks, data storage, GPU acceleration, and train/test optimization loops. Therefore, a basic familiarity with PyTorch is considered a prerequisite for MPoL.
 
-MPoL is *not* an imaging application nor a pipeline, though such programs could be built for specialized workflows with MPoL components. We are focused on providing a numerically correct and expressive set of core primitives so the user can leverage the full power of the PyTorch (and Python) ecosystem to solve their research-grade imaging tasks. This is already a significant development and maintenance burden for the limited resources of our small research team, so our immediate scope must necessarily be limited.
+MPoL is *not* an imaging application nor a pipeline, though MPoL components could be used to build specialized workflows. We are focused on providing a numerically correct and expressive set of core primitives so the user can leverage the full power of the PyTorch (and Python) ecosystem to solve their research-grade imaging tasks. This is already a significant development and maintenance burden for the limited resources of our small research team, so our immediate scope must necessarily be limited.
 
-To get a sense of how MPoL works, please take a look at the {ref}`rml-intro-label` and then the tutorials down below. If you have any questions, please ask us on our [Github discussions page](https://github.com/MPoL-dev/MPoL/discussions).
+To get a sense of what MPoL is and what background material this library assumes, please look at the [](introduction.md). If the package is right for your needs, installation instructions are available [](installation.md). 
 
-If you'd like to help build the MPoL package, please check out the {ref}`developer-documentation-label` to get started. For more information about the constellation of packages supporting RML imaging and modeling, check out the MPoL-dev organization [website](https://mpol-dev.github.io/) and [github](https://github.com/MPoL-dev) repository hosting the source code.
+This documentation provides a short set of tutorials demonstrating key components of the MPoL library. Longer examples demonstrating how one might use MPoL components to build an imaging workflow are packaged together in the [MPoL-dev/examples](https://github.com/MPoL-dev/examples) repository.
+
+If you'd like to help build the MPoL package, please check out the [](developer-documentation.md) to get started. For more information about the constellation of packages supporting RML imaging and modeling, check out the MPoL-dev organization [website](https://mpol-dev.github.io/) and [github](https://github.com/MPoL-dev) repository hosting the source code. If you have any questions, please ask us on our [Github discussions page](https://github.com/MPoL-dev/MPoL/discussions). 
 
 *If you use MPoL in your research, please cite us!* See <https://github.com/MPoL-dev/MPoL#citation> for the citation.
 
 ```{toctree}
 :caption: User Guide
 :maxdepth: 2
 
-rml_intro.md
 introduction.md
 installation.md
 ci-tutorials/PyTorch

docs/rml_intro.md → docs/introduction.md

@@ -1,3 +1,27 @@
+# Introduction and Orientation
+
+2 pages max.
+
+first par
+* restate MPoL as a library w/ maintenance goal
+* highlight science cases: RML imaging, Bayesian inference
+* discuss scope of documentation and need for pre-requisites
+
+second par
+* brief description to what RML is, with call-outs to Zawadzki and other seminal resources.
+
+third par
+* discuss pre-requisites: radio background, 
+* pytorch background
+
+fourth par
+* scope of tutorial examples to follow, showing module building blocks
+* browse the API
+* organization of examples folder
+
+
+
+
 (rml-intro-label)=
 
 # Introduction to Regularized Maximum Likelihood Imaging