Reorganizes the Documentation across the repo. (DickinsonCollege#614)

__Pull Request Description__

This PR reorganizes the documentation as follows:
- CONTRIBUTING focuses on making a first contribution.
- A RESOURCES page is added serves as a pointer to all other
documentation.
- READMEs for each type of work (modules, libraries, api, etc.) are kept
with their code and linked from RESOURCES.
- A root level `docs` folder is added to hold "big picture" docs that
are not tied to a specific directory and are linked from RESOURCES.

- This is not quite complete but is largely complete. After this is
merged it will still be necessary to write a few docs, including:
  - Revise `farmdata2_modules/README.md`
  - Write `farmdata2_modules/fd2_example/README.md`
  - Write `farmdata2_api/README.md`

New issues should be created for each of these when this PR is merged.

Closes DickinsonCollege#609 
Closes DickinsonCollege#610
Closes DickinsonCollege#572 

Changes to the INSTALL.md document were 
Co-authored-by: John MacCormick <[email protected]>
as adapted from his PR DickinsonCollege#612.

---
__Licensing Certification__

FarmData2 is a [Free Cultural
Work](https://freedomdefined.org/Definition) and all accepted
contributions are licensed as described in the LICENSE.md file. This
requires that the contributor holds the rights to do so. By submitting
this pull request __I certify that I satisfy the terms of the [Developer
Certificate of Origin](https://developercertificate.org/)__ for its
contents.

CODE_OF_CONDUCT.md

@@ -1,13 +1,11 @@
-
 # Contributor Covenant Code of Conduct
 
 ## Our Pledge
 
 We as members, contributors, and leaders pledge to make participation in our
 community a harassment-free experience for everyone, regardless of age, body
 type, visible or invisible disability, ethnicity, sex characteristics, gender
-identity and expression, level of experience, education, socio-economic status,
-nationality, personal appearance, race, religion, or sexual identity
+identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, religion, or sexual identity
 and orientation.
 
 We pledge to act and interact in ways that contribute to an open, welcoming,
@@ -39,23 +37,18 @@ Examples of unacceptable behavior include:
 
 ## Enforcement Responsibilities
 
-Community leaders are responsible for clarifying and enforcing our standards of
-acceptable behavior and will take appropriate and fair corrective action in
+Community leaders are responsible for clarifying and enforcing our standards of acceptable behavior and will take appropriate and fair corrective action in
 response to any behavior that they deem inappropriate, threatening, offensive,
 or harmful.
 
 Community leaders have the right and responsibility to remove, edit, or reject
 comments, commits, code, wiki edits, issues, and other contributions that are
-not aligned to this Code of Conduct, and will communicate reasons for moderation
-decisions when appropriate.
+not aligned to this Code of Conduct, and will communicate reasons for moderation decisions when appropriate.
 
 ## Scope
 
-This Code of Conduct applies within all community spaces, and also applies when
-an individual is officially representing the community in public spaces.
-Examples of representing our community include using an official e-mail address,
-posting via an official social media account, or acting as an appointed
-representative at an online or offline event.
+This Code of Conduct applies within all community spaces, and also applies when an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event.
 
 ## Enforcement
 
@@ -94,8 +87,7 @@ of actions.
 **Consequence**: A warning with consequences for continued behavior. No
 interaction with the people involved, including unsolicited interaction with
 those enforcing the Code of Conduct, for a specified period of time. This
-includes avoiding interactions in community spaces as well as external channels
-like social media. Violating these terms may lead to a temporary or
+includes avoiding interactions in community spaces as well as external channels like social media. Violating these terms may lead to a temporary or
 permanent ban.
 
 ### 3. Temporary Ban
@@ -105,9 +97,7 @@ sustained inappropriate behavior.
 
 **Consequence**: A temporary ban from any sort of interaction or public
 communication with the community for a specified period of time. No public or
-private interaction with the people involved, including unsolicited interaction
-with those enforcing the Code of Conduct, is allowed during this period.
-Violating these terms may lead to a permanent ban.
+private interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, is allowed during this period. Violating these terms may lead to a permanent ban.
 
 ### 4. Permanent Ban
 
@@ -118,17 +108,17 @@ individual, or aggression toward or disparagement of classes of individuals.
 **Consequence**: A permanent ban from any sort of public interaction within
 the community.
 
+---
+
 ## Attribution
 
-This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+This Code of Conduct is adapted from the **Contributor Covenant**,
 version 2.0, available at
 https://www.contributor-covenant.org/version/2/0/code_of_conduct.html.
 
 Community Impact Guidelines were inspired by [Mozilla's code of conduct
 enforcement ladder](https://github.com/mozilla/diversity).
 
-[homepage]: https://www.contributor-covenant.org
-
 For answers to common questions about this code of conduct, see the FAQ at
 https://www.contributor-covenant.org/faq. Translations are available at
 https://www.contributor-covenant.org/translations.

LICENSE.md

@@ -1,37 +1,37 @@
-## FarmData2 Licensing Information ##
+# FarmData2 Licensing Information #
 
 FarmData2 is a [Free Cultural Work].  This document outlines the licenses that apply to FarmData2 and the agreement which governs contributions.  Complete copies of these documents can be be found in the [licenses directory]. All copies and forks of FarmData2 must be maintained in compliance with those licenses.
 
 [Free Cultural Work]: https://freedomdefined.org/Definition
 [licenses directory]: licenses
 
-#### Contributions ####
+## Contributions ##
 
 All contributions to FarmData2 will, as a part of FarmData2, be licensed under the applicable license agreements as described below. Thus, before any contribution will be accepted __the contributor must certify that they have the right to grant FarmData2 a license to use, modify and redistribute (with or without further modification) the contributed intellectual property__ under the applicable license agreement. This is done explicitly when when a contributor submits a Pull Request. Every pull request automatically contains a "Licensing Certification" section stating that the contributor certifies that the contribution satisfies the terms of the [Developer Certificate of Origin]. When posting content to any public forums of the project (for example, but not limited to, issue trackers, message boards or discussion areas), the act of posting is here in defined as an implicit certification by the contributor that their contribution satisfies the terms of the [Developer Certificate of Origin].
 
 [Developer Certificate of Origin]: https://developercertificate.org/
 
-#### Intellectual Property ####
+## Intellectual Property ##
 
 As described above, contributors license their intellectual property to FarmData2. Thus, they always retain the copyright to their intellectual property.
 
-#### License Agreements ####
+## License Agreements ##
 
 The code and documentation in FarmData2 are licensed using the following license agreements.
 
-##### Code License #####
+### Code License ###
 
 All code in the FarmData2 project is licensed under the GNU General Public License v3 ([GPL-3.0]).
 
 [GPL-3.0]: https://www.gnu.org/licenses/gpl-3.0.md
 
-##### Content License #####
+### Content License ###
 
 All other content, including code snippets posted in public forums, is licensed under the Creative Commons Attribution-ShareAlike 4.0 International License ([CC-BY-SA-4.0]).
 
 [CC-BY-SA-4.0]: https://creativecommons.org/licenses/by-sa/4.0/
 
-#### Attribution ####
+## Attribution ##
 
 Attribution of contributions to the FarmData2 repository are maintained in the logs of the git version control system.
 

README.md

@@ -1,30 +1,35 @@
-## FarmData2 ##
+# FarmData2 #
 
 FarmData2 is an application that supports the operation and certification requirements for small organic farming operations.
 
-### Description ###
+## Description ##
 
 FarmData2 is a web application for recording and reporting on crop and livestock production within the context of small organic farming operations.  Crop production records include seeding, transplanting, harvest, cover crop, compost, fertilization, irrigation, pest scouting, and spray activities.  Livestock production records track animals from birth to slaughter or sale and include pasture moves, periodic and veterinary care and logging of egg production.  Records of packing, distribution and customer invoicing are also maintained.  All records and reporting features are designed to closely align with organic certification requirements and to support the certification and recertification process.
 
-### Connecting ###
+## Connecting with the Community ##
 
-Connect with the [FarmData2 community on Zulip](https://farmdata2.zulipchat.com/).
+Have questions? Want to find something to do? Want to learn more? 
 
-If you are unfamiliar with [Zulip](https://zulip.com/) it is a group chat application that blends the benefits of threaded discussions with live chat. Zulip is relatively easy to use once you understand the key ideas of [streams and topics](https://zulip.com/help/about-streams-and-topics).
+Connect with the FarmData community through the following channels:
+  - [FarmData2 streams on Zulip](https://farmdata2.zulipchat.com/)
+  - [FarmData2 Issue Tracker](https://github.com/DickinsonCollege/FarmData2/issues)
+  - [FarmData2 Pull Requests](https://github.com/DickinsonCollege/FarmData2/pulls)
 
-### Installing FarmData2 ###
+Not sure which channel to use? The [Communications Document](docs/Communications.md) describes each of these communications channels and how each is typically used.
 
-If you are interesting in trying or using FarmData2 see the [INSTALL Document](INSTALL.md) for information about how to get started.
+## Installing FarmData2 ##
 
-### Contributing to FarmData2 ###
+If you are interesting in trying, using or contributing to FarmData2 see the [INSTALL Document](INSTALL.md) for information about how to get started.
 
-If you are interesting in contributing to the development of FarmData2 see the [CONTRIBUTING Document](CONTRIBUTING.md) for information about how to get started.
+## Contributing to FarmData2 ##
 
-### History ###
+If you are interesting in contributing to the development of FarmData2 see the [CONTRIBUTING Document](CONTRIBUTING.md) for information about how to make your first contribution.  The [Other Ways to Contribute Document](docs/WaysToContribute.md) has additional ideas for how you might engage with FarmData2.  The [RESOURCES Document](RESOURCES.md) contains pointers to more detailed project documentation.
+
+## History ##
 
 FarmData2 is both a _second_ edition of it predecessor, FarmData, and the integration of _two_ related projects FarmData and AnimalData. These projects were conceived and built by Tim Wahls, Matt Steiman and many students to support operation of the Dickinson College Farm.  The FarmData2 project was initiated as a part of curricular redesign in the Computer Science Department at Dickinson College.  It is now an active part of several courses in the curriculum.  It provides students in these courses with early and sustained opportunities to learn and practice modern software development within the context of an open source software community.
 
-### Acknowledgements ###
+## Acknowledgements ##
 
 FarmData2 is powered by the farmOS open source project.
 

RESOURCES.md

@@ -0,0 +1,69 @@
+# FarmData2 Resources #
+
+This document is a single source for information about FarmData2. It is organized as a list of links that point to documentation that addresses common tasks that arise in working on FarmData2.
+
+## Key Information ##
+
+  - [Main Repository](https://github.com/DickinsonCollege/FarmData2)
+  - [Code of Conduct](CODE_OF_CONDUCT.md)
+  - [Licensing Information](LICENSE.md)
+
+## Communication ##
+
+  - [How to Communicate in FarmData2](docs/Communications.md)
+  - The Communication Channels:
+    - [The FarmData2 community on Zulip](https://farmdata2.zulipchat.com/)
+    - [Issue Tracker](https://github.com/DickinsonCollege/FarmData2/issues)
+    - [Pull Requests](https://github.com/DickinsonCollege/FarmData2/pulls)
+
+## Getting Started ##
+
+  - [Installing FarmData2](INSTALL.md) also includes:
+    - Starting and stopping FarmData2
+    - Connecting to the development environment
+    - Login credentials for:
+      - the sample farm 
+      - the development environment
+      - mariaDB / phpMyAdmin
+
+## Ways to Contribute ##
+
+  - [Fixing Bugs or Adding Features](CONTRIBUTING.md)
+  - [Other Ways to Contribute](docs/WaysToContribute.md)
+
+## Learn FarmData2 Basics ##
+
+  - [FarmData2 School](farmdata2/farmdata2_modules/fd2_school/README.md)
+  - [FarmData2 Organization](docs/Organization.md)
+  - [FarmData2's Technologies](docs/Technologies.md)
+
+## Front End Development ##
+
+  - [The `fd2_example` Module](farmdata2/farmdata2_modules/fd2_example/README.md)
+  - [Creating FarmData2 Modules](farmdata2/farmdata2_modules/README.md) includes:
+    - Creating New Modules
+    - End-to-End Tests for Modules
+    - Using FarmData2 Library Functions
+    - Using FarmData2 Vue.js Components
+  - [The `fd2_config` Module](farmdata2/farmdata2_modules/fd2_config/README.md)
+  - [FarmData2 Front End Resources](farmdata2/farmdata2_modules/resources/README.md) includes:
+    - The FarmData2 JavaScript library
+    - The FarmData2 Vue.js Components
+
+## Back End Development ##
+
+  - [The FarmData2 API](farmdata2/farmdata2_api/README.md) also includes:
+    - Using phpMyAdmin
+
+## The Sample Database ##
+
+  - [The FarmData2 Sample Database](docker/sampleDB/README.md) also includes:
+    - Description of the data
+    - Building/rebuilding the databases  
+
+## FarmData2 Infrastructure ##
+
+  - [Overview of FarmData2 Containerization](docker/README.md) also includes:
+    - Descriptions of the Docker images
+    - Building/updating Docker images
+

docker/README.md

@@ -36,6 +36,26 @@ FarmData2 opts to pull all images from its own dockerhub repository to allow us
 
 The images that are used are specified in the `docker/docker-compose.yml` file.
 
+## Persistence in Containers ##
+
+The [`docker/fd2-up.bash`](docker/fd2-up.bash) and [`docker/fd2-down.bash`](docker/fd2-down.bash) scripts start and stop all of the containers necessary for FarmData2. Some key points about how information is persisted between container starts and stops are described below.  The full details can be found in the [`docke/docker-compose.yml`](docker/docker-compose.yml) file.
+
+### Writeable Layers ###
+
+When `./fd2-down.bash` is run `docker-compose` removes all of the containers, including their writeable layers.  The containers are all recreated, including blank writeable layers, each time the `fd2-up.bash` is used. However, all of the FarmData2 data and code is mounted from the development machine and thus will persist between uses. You can find all of the details of the mounted volumes in the `docker-compose.yml` file.
+
+### The FarmData2 Repository ###
+
+The `FarmData2` repository on the host machine is mounted into `/home/fd2dev/FarmData2` in the FarmData2 development container.  The `FarmData2/contrib_modules` and the `FarmData2/farmdata2_modules` directories are mounted into the appropriate locations in the farmOS container. Thus, any changes made to the contents of the these directories either in the FarmData2 development environment or on the host machine will be reflected in the containers.
+
+### The Database ### 
+
+The farmOS/drupal database used by FarmData2 is stored in a Docker volume (`docker_farmos_db`)that is mounted into the FarmData2 development environment at `docker/db` and into the Maria DB container at `/var/lib/mysql`.  Using the Docker volume rather than the host filesystem to persist the database provides a significant performance boost.
+
+### The Dev Environment ###
+
+The `home/fd2dev` directory in the FarmData2 development development environment is stored in a Docker volume (`docker_farmdev_home_fd2.x`).  If it is necessary to make breaking changes to the development environment the version number of the container and the volume will be bumped in the `docker/docker-compose.yml` file which will create a new container and use a new blank volume the next time `fd2-up.bash` is run.
+
 ## Building the Images
 
 The `docker/build-images.bash` script builds the images and pushes them to dockerhub. Run this script with no parameters to see a *usage* message describing how to build and push an image.
@@ -53,4 +73,5 @@ When an image is modified the tag in its `repo.txt` file should be incremented.
 
 When a new tag is created and pushed, the `docker-compose.yml` file should also be updated to use the new tag for the image.  This ensures that the latest images will be pulled for developers the next time they use `fd2-up.bash` to start FarmData2 after they synch with the upstream repository.
 
-If significant changes are made to the `dev` container then it may also be necessary to bump the version number of the Docker volume that is used to store the fd2dev user's home directory. This will cause a new volume to be created for the user's home directory.
+If significant changes are made to the `dev` container then it may also be necessary to bump the version number of the Docker volume that is used to store the fd2dev user's home directory. This will cause a new volume to be created for the user's home directory.
+

docs/Communications.md

@@ -0,0 +1,16 @@
+# Communications in FarmData2 #
+
+FarmData2 uses three primary communications channels.  Each channel serves a slightly different purpose.  When communicating with the community try to pick the most appropriate channel.  
+
+  - [The FarmData2 community on Zulip][zulipCommunity]
+    - The Zulip community is the place where you can introduce yourself to the FarmData2 community, ask and answer questions about using FarmData2, developing FarmData2, the installation process, how to get started or technology. If you have a tentative idea for a new feature or are unsure if what you are seeing is a bug, the Zulip streams are a good place to have an initial conversation before creating a ticket in the Issue Tracker (below).  If you are unsure who to ask or how to ask, start by reaching out on Zulip. The project maintainers monitor the Zulip streams and will respond to questions there.
+
+  - [Issue Tracker][issueTracker]
+    - If you want to report a bug, want to request a new feature, have an idea about how address an existing issue, have started working on an issue and have questions, then the Issue Tracker is the channel to use. If you have thoughts or questions about an issue with an existing ticket in then adding comments to that ticket is the appropriate way to communicate. If you need to report a bug for which there is no ticket or you want to request a new feature, then creating a new ticket is the appropriate approach. There are links to additional information on reporting new bugs or requesting new features on the [HOW_TO](../HOW_TO.md) page. 
+
+  - [Pull Requests][pullRequests]
+    - If you have specific code or documentation changes that you want to contribute or partially coded bug fixes or implementations that you want to discuss then a pull request is the appropriate channel. For contributions that you believe are complete make a normal pull request.  A project maintainer will review your request and will communicate with you through comments on the pull request if revisions are needed.  If your changes are not complete but you have questions or would like input from a project maintainer then make a *draft pull request*.  Explain the purpose of your pull request in the body and include a link to the ticket for the issue you are addressing (e.g. Closes #123). Then add a comment to the pull request asking the specific question about your code or documentation.
+
+[issueTracker]: https://github.com/DickinsonCollege/FarmData2/issues
+[pullRequests]: https://github.com/DickinsonCollege/FarmData2/pulls
+[zulipCommunity]: https://farmdata2.zulipchat.com/