Merge pull request #96 from usds/getting-started

Docs: Getting Started content for Documentation

docs/README.md

@@ -1,8 +1,9 @@
 # US Forms System Documentation
 
 - [Getting started with the Forms System Library](getting-started/README.md)
-  - Creating a new application with the US Forms System Starter App
-  - Installing the library in an existing application
+  - [Tools for getting started with the US Forms System](#tools-for-getting-started-with-the-us-forms-system)
+  - [Creating a new application with the US Forms System Starter App](getting-started/creating-a-new-application-with-the-us-forms-system-starter-app.md)
+  - [Installing the US Forms System in an existing application](getting-started/installing-the-library-in-an-existing-application.md)
 - [Building a form](building-a-form/README.md)
   - [About the US Forms System library](building-a-form/about-the-us-forms-system-library.md)
   - [Creating a form config file](building-a-form/creating-a-form-config-file.md)

docs/getting-started/README.md

@@ -1,7 +1,17 @@
-# Getting started with the Forms System Library
+# Getting started with the US Forms System
 
-### Creating a new application with the US Forms System Starter App
+Depending on your needs, you can either create a brand new application from scratch or install the US Forms System in an existing application.
 
-### Installing the library in an existing application
+### [Tools for getting started with the US Forms System](#tools-for-getting-started-with-the-us-forms-system)
+
+Building a form using the US Forms System requires some minimum front-end development tools, as well as general knowledge of those tools. Where possible, we'll provide links to information about getting started with these tools.
+
+### [Creating a new application with the US Forms System Starter App](creating-a-new-application-with-the-us-forms-system-starter-app.md)
+
+The US Forms System Starter App creates the initial files, configuration, build process, and web server you need to start building your form immediately.
+
+### [Installing the US Forms System in an existing application](installing-the-library-in-an-existing-application.md)
+
+If you're using an existing React application, you can install the US Forms System in that app.
 
 [Back to *US Forms System Documentation*](/docs/README.md)

docs/getting-started/creating-a-new-application-with-the-us-forms-system-starter-app.md

@@ -0,0 +1,61 @@
+# Creating a new application with the US Forms System Starter App
+
+The US Forms System Starter App creates the initial files, configuration, build process, and web server you need to start building your form.
+
+Before you begin, review "[Tools for getting started with the US Forms System](getting-started/tools-for-getting-started-with-the-us-forms-system)."
+
+### In this guide
+
+- [Clone the Starter App repository and change the remote URL](#clone-the-starter-app-repository-and-change-the-remote-url)
+- [Install dependencies](#install-dependencies)
+- [Build and run your app](#build-and-run-your-app)
+
+### Clone the Starter App repository and change the remote URL
+
+1. Clone the us-forms-system-starter-app repository to your computer:
+```bash
+$ git clone https://github.com/usds/us-forms-system-starter-app.git
+```
+2. Change the current directory to the new us-forms-system-starter-app directory:
+```bash
+$ cd us-forms-system-starter-app
+```
+3. [On GitHub, create a new repository](https://help.github.com/articles/creating-a-new-repository/) named for your new forms app.
+4. From your new repository on GitHub, [copy the clone URL](https://help.github.com/articles/cloning-a-repository/).
+5. In Terminal (Mac and Linux) or the Command Prompt (Windows), review the current remote URL that's set to `origin`. The `fetch` and `push` URLs should be set to `https://github.com/usds/us-forms-system-starter-app.git`:
+```bash
+$ git remote -v
+# Lists all remote repositories, along with the URL for those remotes.
+origin https://github.com/usds/us-forms-system-starter-app.git (fetch)
+origin https://github.com/usds/us-forms-system-starter-app.git (push)
+```
+6. Change your `origin` to use the URL for the new remote repository you created in Step 3 and copied in Step 4:
+```bash
+$ git remote set-url origin https://github.com/YOUR-USERNAME/YOUR-NEW-REPOSITORY-NAME.git
+# Changes 'origin' to the new remote's URL
+```
+7. Review your current remote URL again. `origin` should be set to *your* repository on GitHub, not https://github.com/usds/us-forms-system-starter-app.git:
+```bash
+$ git remote -v
+# Lists all remote repositories, along with the URL for those remotes.
+origin https://github.com/YOUR-USERNAME/YOUR-NEW-REPOSITORY-NAME.git (fetch)
+origin https://github.com/YOUR-USERNAME/YOUR-NEW-REPOSITORY-NAME.git (push)
+```
+
+### Install dependencies
+
+Use npm to install dependencies specified in `us-forms-system-starter-app/package-lock.json`.
+
+1. [Make sure Node and npm are installed](tools-for-getting-started-with-the-us-forms-system#node-js-and-npm).
+2. In Terminal (Mac and Linux) or the Command Prompt (Windows), use npm to install dependencies for the Starter App:
+```bash
+$ npm install
+```
+
+### Build and run your app
+
+Once your repository is set up and dependencies are installed, you can begin building your app by editing `/js/config/form.js`. For more information, see "[Creating a form config file](building-a-form/creating-a-form-config-file.md)."
+
+To run your app locally, in Terminal (Mac and Linux) or the Command Prompt (Windows), type `npm start`. Once the server has started, you can view your form in a browser window at `localhost:8080`.
+
+[Back to *Getting Started with the US Forms System*](README.md)

docs/getting-started/installing-the-us-forms-system-in-an-existing-application.md

@@ -0,0 +1,36 @@
+# Installing the US Forms System in an existing application
+
+If you're using an existing React application, you can install the US Forms System in that app.
+
+Before you begin, review "[Tools for getting started with the US Forms System](getting-started/tools-for-getting-started-with-the-us-forms-system)."
+
+### In this guide
+
+- [Install the library and dependencies](#install-the-library-and-dependencies)
+- [Create required files](#create-required-files)
+
+### Install the library and dependencies
+
+1. Install the library:
+```bash
+npm install --save https://github.com/usds/us-forms-system.git
+```
+
+2. Install the [US Web Design System](https://github.com/uswds/uswds) and React dependencies:
+```bash
+npm install --save-dev uswds@^1.6.3
+npm install --save-dev react@^15.5.4
+npm install --save-dev react-dom@^15.6.2
+```
+
+### Create required files
+
+To enable your form, create the following files. For an example of these files, see the [us-forms-system-starter-app repository](https://github.com/usds/us-forms-system-starter-app).
+
+- A [form config file](https://github.com/usds/us-forms-system-starter-app/blob/master/js/config/form.js). For more information, see "Creating a form config file."
+- An entry [app.js](https://github.com/usds/us-forms-system-starter-app/blob/master/app.js) file.
+- A [React component](https://github.com/usds/us-forms-system-starter-app/blob/master/js/components/Form.jsx) to render the top-level us-forms-system component.
+- A [routes file](https://github.com/usds/us-forms-system-starter-app/blob/master/js/routes.jsx) that loads `createRoutes` from us-forms-system. This automatically creates the routes from the form config file.
+- A [reducers file](https://github.com/usds/us-forms-system-starter-app/blob/master/js/reducers.js) that loads `createSchemaFormReducer` from us-forms-system. This creates the app's reducer functions.
+
+[Back to *Getting Started with the US Forms System*](README.md)

docs/getting-started/tools-for-getting-started-with-the-us-forms-system.md

@@ -0,0 +1,36 @@
+# Tools for getting started with the US Forms System
+
+Building a form using the US Forms System requires some minimum front-end development tools, as well as general knowledge of those tools. Where possible, we'll provide links to information about getting started with these tools.
+
+### In this guide
+
+- [Command line interface (CLI)](#command-line-interface-cli)
+- [JavaScript](#javascript)
+- [Node.js and npm](#node-js-and-npm)
+- [React](#react)
+- [JSON Schema](#json-schema)
+- [react-jsonschema-form (rjsf)](#react-jsonschema-form-rjsf)
+
+### Command line interface (CLI)
+
+You should be comfortable using command line tools such as Terminal (Mac and Linux) or Command Prompt (Windows). These tools come pre-installed on nearly all computers. There are several tutorials of various types available online to learn about the CLI.
+
+### JavaScript
+
+Most technologies the US Forms System uses, such as React, are centered around JavaScript. We recommend basic familiarity with JavaScript to build forms with the US Forms System. For more information about JavaScript, including tutorials for getting started, see [Pluralsight's JavaScript website](https://www.javascript.com/).
+
+### Node.js and npm
+
+Node.js is a JavaScript runtime environment that allows you to execute complete JavaScript programs. When you install Node.js, it automatically installs a package manager called npm. You need both Node.js (minimum version 8.0.0) and npm to develop using the US Forms System. For more information, including installation instructions, see the [Node.js website](https://nodejs.org).
+
+### React
+
+React is a JavaScript library for building user interfaces (UI). For more information, including tutorials for getting started, see the [React.js website](https://reactjs.org/).
+
+##### JSON Schema
+
+JSON Schema is a concise method of describing JSON data. We recommend basic familiarity with JSON Schema to build forms with the US Forms System. For more information about JSON Schema, see [Understanding JSON Schema](https://spacetelescope.github.io/understanding-json-schema/) by the Space Telescope Science Institute.
+
+##### react-jsonschema-form (rjsf)
+
+rjsf is a React component maintained by Mozilla that's used to build web forms based on JSON Schema. For more information, see the [react-jsonschema-form documentation](https://github.com/mozilla-services/react-jsonschema-form#react-jsonschema-form).