updated docs

README.md

@@ -2,33 +2,33 @@
 
 [![CircleCI](https://circleci.com/gh/JaneliaSciComp/workstation.svg?style=svg)](https://circleci.com/gh/JaneliaSciComp/workstation)
 
-The Janelia Workstation is a neuroscience discovery platform for processing, analysis, annotation, and sharing of large-scale 3d microscopy data.
+The Janelia Workstation is a neuroscience discovery platform for processing, analysis, annotation, and sharing of large-scale 3D microscopy data. 
 
 ![Workstation Screenshot](docs/screenshot.png)
 
 The Janelia Workstation currently supports two large-scale team projects at Janelia Research Campus:
-* The [MouseLight](https://www.janelia.org/project-team/mouselight) tools have been fully open sourced and made available here with complete documentation. These tools enable neuron tracing and connectomics on terabyte-scale Mouse brain volumes. 
-* The [FlyLight](https://www.janelia.org/project-team/flylight) tools have been partially open sourced, and not yet officially supported. At Janelia, these tools support search, browsing, and annotation of millions of confocal-imaged Fly nervous systems. In the future they will be fully released here.
+* The **HortaCloud** application built for [MouseLight](https://www.janelia.org/project-team/mouselight) has been fully open sourced and made available here with complete documentation. These tools enable neuron tracing and connectomics on terabyte-scale Mouse brain volumes. 
+* The [FlyLight](https://www.janelia.org/project-team/flylight) tools have been partially open sourced, but are not yet officially supported. At Janelia, these tools support search, browsing, and annotation of millions of confocal-imaged Fly nervous systems. 
 
 ## License and Citation Agreement
 
-This software uses a modified Janelia Open Source License, and requiring [citation](https://doi.org/10.25378/janelia.8182256.v1) when used in studies or publications. [For details see here](LICENSE.md).
+This software uses a modified Janelia Open Source License, and requiring [citation](https://doi.org/10.25378/janelia.8182256.v1) when used for studies or publications. [For details see here](LICENSE.md).
 
 ## For Users
 
 Read the [User Manual](docs/UserManual.md) to find out more about the Workstation's capabilities and how to use them.
 
 ## For System Administrators
 
-### System Installation
+### Deployment
 
-The Workstation Client (this repository) is supported by a set of back-end services. Deploying all of these services is easily accomplished through the use of Docker containers. Complete documentation about deploying the entire system is available in the [jacs-cm](https://github.com/JaneliaSciComp/jacs-cm) repository.
+The Workstation Client (this repository) is supported by a set of back-end services. Deploying all of these services is easily accomplished through the use of Docker containers orchestrated with either Docker Compose or Docker Swarm. Complete documentation about deploying the entire system is available in the [jacs-cm](https://github.com/JaneliaSciComp/jacs-cm) repository.
 
 ### MouseLight Deployment
 
 The canonical two-server deployment of the MouseLight neuron tracing tools is described [here](https://github.com/JaneliaSciComp/jacs-cm/blob/master/docs/MouseLightDeployment.md). 
 
 ## For Developers
 
-For information about building this code base, see the [Release Process](docs/ReleaseProcess.md) documentation.
+For information about building this code base, see the [Development](docs/Development.md). To create an official release, see the [Release](docs/ReleaseProcess.md) documentation.
 

docs/Development.md

@@ -1,6 +1,8 @@
 # Development
 
-## Compile
+The Janelia Workstation is built on top of the [Apache NetBeans Platform](https://netbeans.apache.org/kb/docs/platform/). It is recommended for developers to get familiar with the concepts used in this framework before diving into Workstation development. The best starting point is _The Definitive Guide to NetBeans Platform_ by Heiko Bock. 
+
+## Building
 
 To build the Janelia Workstation application for Janelia Research Campus, use the `janeliaws` profile:
 ```
@@ -12,7 +14,7 @@ To build the Janelia HortaCloud application, use the `horta` profile:
 mvn --batch-mode -T 8 -Djava.awt.headless=true -P horta clean install
 ```
 
-## Run
+## Running 
 
 To run the Janelia Workstation application, use the `janeliaws` profile:
 ```
@@ -24,7 +26,7 @@ To run the Janelia HortaCloud application, use the `horta` profile:
 mvn --batch-mode -T 8 -Djava.awt.headless=true -P horta nbm:cluster-app nbm:run-platform
 ```
 
-## IntelliJ Debugging
+## Debugging in IntelliJ
 
 There are many ways to set up 
 [debugging in IntelliJ](https://www.jetbrains.com/help/idea/attaching-to-local-process.html). Here's one way, where you can run the Workstation normally each time and add a debugger if you need it:
@@ -47,7 +49,7 @@ To add a module, create a new directory for your module under modules/ and creat
 * `src/main/nbm/manifest.mf`
 * `src/main/resources/org/janelia/workstation/<module>/Bundle.properties`
 
-You can follow any of the existing modules as a guide for the content of these files. Make sure to change the module's **name** and **artifact** in `pom.xml`!
+You can follow any of the existing modules as a guide for the content of these files. Make sure to change the module's **name** and **artifact** in `pom.xml`.
 
 Next, edit `pom.xml` at the top-level and add your module to the `<modules>` section at the bottom. This will make it part of the build.
 

docs/ReleaseProcess.md

@@ -1,8 +1,20 @@
 # Release Process
 
-The Workstation client is built and distributed using the Apache NetBeans Platform. There are several versions which need to be updated when creating a new release:
+The Workstation client is built and distributed using the [Apache NetBeans Platform](https://netbeans.apache.org/kb/docs/platform/). To create a release, ensure you are on the master branch, with all code checked in, then run the release script:
 
-## Module Versioning
+    ./release.sh <version>
+
+The version number should be in [Semantic Versioning](https://semver.org/) style. This release process automatically increments all module versions, and sets the overall Workstation version. You can then proceed over to the [jacs-cm](https://github.com/JaneliaSciComp/jacs-cm) repository to rebuild the workstation-site container using your newly released Workstation version.
+
+## Docker Build
+
+The easiest way to distribute the Workstation is to use the [Docker Container](https://hub.docker.com/r/janeliascicomp/workstation-site). Running this container serves a static website where you can download the Workstation installer, and the Update Center for update distribution. You can build your own customized container by using the [jacs-cm](https://github.com/JaneliaSciComp/jacs-cm) tools. 
+
+## Manual Release 
+
+The release process above automates several things that can be run manually. These are documented below for completeness, but shouldn't be necessary for a normal release.
+
+### Module Versioning
 
 The modules are versioned with the NetBeans module system, which allows for updates of existing clients through the NetBeans Update Center mechanism.
 
@@ -11,31 +23,27 @@ To increment the global module version, edit the main pom.xml and increment **ja
 Some modules are rarely updated, and those are version pinned and need to changed independently. For example, to release a new version of the DarculaLAF module (normally pinned), edit ./modules/DarculaLAF/src/main/nbm/manifest.mf, and increment **OpenIDE-Module-Specification-Version**.
 
 
-## Workstation Version
+### Workstation Version
 
-To increment the overall version of the Workstation, you can use Maven, For example, to set the version to 9.0:
+To increment the overall version of the Workstation artifacts, we use Maven. For example, to set the version to 9.0:
 ```
-mvn versions:set -DnewVersion=8.0 -DgenerateBackupPoms=false
+mvn versions:set -DnewVersion=9.0 -DgenerateBackupPoms=false
 ```
 
-This version isn't actually used for anything currently, but should be maintained anyway because it creates a version history of artifacts within Maven.
+This version isn't actually used in the built application, but should be maintained anyway because it creates a version history of artifacts within Maven.
 
 
-## Production Release
+## Git Version Tagging
 
-To release the code to production, first tag it remotely with a version number:
+Tag the code base with your version number:
 ```
-git tag 8.0-RC8
-git push origin 8.0-RC8
+git tag 9.0
+git push origin 9.0
 ```
 
 Now you can use this version number to build and deploy the **workstation-site** container with the jacs-cm tools.
 
-## Docker Build
-
-The easiest way to distribute the Workstation is to use the [Docker Container](https://hub.docker.com/r/janeliascicomp/workstation-site). Running this container serves a static website where you can download the Workstation installer, and the Update Center for update distribution. You can build your own customized container by using the [jacs-cm](https://github.com/JaneliaSciComp/jacs-cm) tools. 
-
-## Manual Build
+## Manual Production Build
 
 The build can also be done manually, as follows:
 
@@ -63,4 +71,3 @@ mvn -f modules/applications/pom.xml --batch-mode -T 8 -Djava.awt.headless=true -
 ```
 
 Once the build is complete, the installers and update center will be available under the **modules/application/target** directory.
-