Update schema descriptions

README.md

@@ -6,3 +6,7 @@
 Let admins configure their JupyterHub via a GUI
 
 ![](docs/_static/screenshot.png)
+
+## Contribute
+
+See [the contributing documentation](docs/contributing.md) for information about how to contribute to this package.

docs/contributing.md

@@ -8,7 +8,7 @@
 2. A set of mixins to be used with your JupyterHub spawner for dynamic configuration
 3. A [react](https://reactjs.org/) based frontend
 
-
+(contributing:backend)=
 ## Backend & JupyterHub
 
 Since `jupyterhub-configurator` is run as a JupyterHub service, it is best developed
@@ -39,22 +39,49 @@ the backend.
 
 ## Frontend
 
-You need [npm](https://www.npmjs.com/) to work on the frontend, which is contained inside
-the `frontend/` directory.
+This section describes how to set up the right environment and make contributions to the front-end.
+
+### Location of files
+
+The configuration and files for the frontend are contained in the `frontend/` folder.
+Most of the files in this folder are configuration for webpack and npm, to control the dependencies and steps needed to build the JavaScript.
+
+The `src/` folder contains the files that define the look and feel of the configurator.
+These are mostly arranged into **components** with JavaScript and CSS defined for each section of the configurator page.
+
+The `src/schema.json` file defines the text and structure of the configurator. If you want to edit a description, title, or prompt, this is the place to do it.
+
+When you build the frontend assets via the steps below, these are compiled into a single JavaScript file, and placed in `jupyterhub_configurator/static/`.
+**Do not edit this file**, it is programmatically generated.
+
+### Make a change to the frontend
 
-1. Get inside the `frontend/` directory and install required dependencies
+To make a change to the frontend, take these steps:
+
+1. Install `npm`. We use NPM to build the JavaScript for serving the UI. [Here are download instructions for `npm`](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm/).
+2. Switch into the `frontent/` directory:
+
+   ```console
+   $ cd frontend
+   ```
+
+3. Install required dependencies with `npm`.
 
    ```bash
-   cd frontend
-   npm i
+   npm install --no-package-lock
    ```
 
-2. We use [webpack](https://webpack.js.org/) to build our dependencies, and it can
-   automatically rebuild whenever you make a change.
+   This will install all of the necessary `npm` packages to build the configurator.
+   Note that the `--no-package-lock` flag will prevent `npm` from over-writing the `package-lock.json` file.
+   If you **want** to do this, simply run `npm install` without that flag.
+
+4. Build the dependencies. We use [webpack](https://webpack.js.org/) to build our dependencies. Run it with this command
 
-   ```bash
-   npm run dev
+   ```console
+   $ npm run dev
    ```
 
-3. Your configurator page should now be running your latest local build of JS.
-   You have to refresh the page to pick up any changes.
+   This will build the dependencies and watch the relevant files for any changes, re-building as necessary.
+
+5. Your configurator page should now be running your latest local build of JS.
+   You can preview the results by running the configurator with your JupyterHub (see [](contributing:backend) for more information). You'll need to **refresh the page** to see any changes.

frontend/src/schema.json

@@ -6,7 +6,7 @@
       "type": "string",
       "title": "User docker image",
       "description": "Determines languages, libraries and interfaces available",
-      "help": "Leave this blank to use the default"
+      "help": "For example: quay.io/2i2c/myimagename:cb5757e7c9f8. Leave this blank to use the default."
     },
     "Spawner.default_url": {
       "type": "string",
@@ -18,17 +18,17 @@
           {
             "value": "/tree",
             "title": "Classic Notebook",
-            "description": "What most people think of as Jupyter"
+            "description": "The original web application for creating and sharing computational documents"
           },
           {
             "value": "/lab",
             "title": "JupyterLab",
-            "description": "Powerful next generation notebook interface"
+            "description": "The latest web-based interactive development environment"
           },
           {
             "value": "/rstudio",
             "title": "RStudio",
-            "description": "Very popular R IDE"
+            "description": "A very popular R IDE from the company RStudio"
           }
         ]
       }