Docs: Getting Started content for Documentation #96

bernars-usa · 2018-06-20T18:23:51Z

This reorganizes the Getting Started content that existed in https://github.com/usds/us-forms-system/blob/master/docs/getting-started.md. This is a branch off of #90, and addresses part of #86.

I'm looking for feedback on organization as well as technical accuracy. There are likely gaps in information here as well; if you feel like pointing those out here, please do, otherwise we can add more in another pass after the reorganization. Up to you, dear reviewer.

cc @usds/forms-system

bernars-usa · 2018-06-20T18:30:08Z

docs/getting-started/installing-the-library-in-an-existing-application.md

+
+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."


I'd love to give more information about these files, if there's anything to elaborate on.

Yep, that's fair. These are pretty standard files needed for a generic React app. I wonder how much we should explain here and how much we should expect people to know from React. Would love your thoughts on this.

I wonder how much we should explain here and how much we should expect people to know from React.

I'll look into what React resources exist and see if there's anything easily linkable. 👍

annekainicUSDS

This looks great! Just a few minor comments

annekainicUSDS · 2018-06-21T18:31:50Z

docs/getting-started/README.md

@@ -1,7 +1,13 @@
 # Getting started with the Forms System Library

-### 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 Library in an existing application.


This is nitpicky, but I notice sometimes we refer to this library as US Forms System, or US Forms Library, or Forms System Library. We might just want to pick 1 name and be consistent.

Yes, we definitely need to standardize. Will poll on which we like. 👍

Per conversation in HipChat, we're going to go with US Forms System.

annekainicUSDS · 2018-06-21T18:33:44Z

docs/getting-started/README.md

+
+### [Installing the library in an existing application](getting-started/installing-the-library-in-an-existing-application.md)
+
+If your existing application has a web server to run the app locally, you can install the US Forms System Library in that app.


I think the real distinction of why you would want to go this route is less about the existence of a web server and more about just having an existing React app that you want to integrate us-forms-system into, so I might change this content to reflect that. Let me know if that doesn't make sense!

That makes a ton of sense, and is a much better description. I'll incorporate that!

annekainicUSDS · 2018-06-21T18:34:01Z

docs/getting-started/installing-the-library-in-an-existing-application.md

@@ -0,0 +1,35 @@
+# Installing the library in an existing application
+
+If your existing application has a web server to run the app locally, you can install the US Forms System Library in that app.


Same comment as above

annekainicUSDS · 2018-06-21T18:35:00Z

docs/getting-started/installing-the-library-in-an-existing-application.md

+
+1. Install the library:
+```bash
+npm install --save https://github.com/usds/us-forms-system.git


Once we move to publish this library as an npm package, we'll have to update these instructions. Need to remind myself to do this at that point!

annekainicUSDS · 2018-06-21T18:36:14Z

docs/getting-started/installing-the-library-in-an-existing-application.md

+
+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."


Yep, that's fair. These are pretty standard files needed for a generic React app. I wonder how much we should explain here and how much we should expect people to know from React. Would love your thoughts on this.

bernars-usa · 2018-06-21T18:57:25Z

docs/getting-started/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.
+
+For more information, including app installation instructions, see the [US Forms System Starter App README](https://github.com/usds/us-forms-system-starter-app#us-forms-system-starter-app).


I was talking to @fatimanoorva this afternoon about where to put the instructions for setting up the starter app. I'm leaning toward wanting to keep the instructions in this repo alongside the other docs, rather than keeping two sets of docs in separate repos. Thoughts/feelings?

There's also an issue open about needing to enhance those instructions (#79). I'm working on getting the starter app running on my machine, too, and taking notes.

bernars-usa · 2018-06-21T19:45:17Z

Besides the failing CI, this is ready for another round of reviews. Thanks for the first pass, @annekainicUSDS!

bernars-usa · 2018-06-22T17:26:24Z

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

+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.


@annekainicUSDS - Is this an acceptable description?

yes I think so

bernars-usa · 2018-06-22T17:27:35Z

docs/getting-started/README.md


-### 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. For more information about React apps, see the [React project's Hello World tutorial](https://reactjs.org/docs/hello-world.html).


I added a link to a React tutorial here. Let me know if that feels like overkill.

bernars-usa · 2018-06-22T17:30:06Z

@usds/forms-system - This is ready for a final review. Note that it's not going into master, so we can iterate more later.

bernars-usa · 2018-06-29T20:00:51Z

I've actually returned to this PR to incorporate some of the notes and thoughts in #79. I'll drop a comment when this is ready for review (again).

…f the others

…cloning

bernars-usa · 2018-07-02T17:55:32Z

This is ready for review (again). Based on conversation in #79 and #87, this PR now includes:

An article describing the tools/knowledge one should have to be successful ("Tools for getting started with the US Forms System")
Instructions for installing the starter app using the clone method + updating origin, plus more verbose instructions all around ("Creating a new application with the US Forms System Starter App")

Navigate through the whole map topic here (💻 Rendered): "Getting started with the US Forms System"

annekainicUSDS

LGTM! A couple of minor comments

annekainicUSDS · 2018-07-03T18:19:36Z

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

+
+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`.


Maybe we should add a line that says, "Once the server has started you should be able to view your form at localhost:8080". It also says this in the server output in the terminal, but it might be useful to include here anyway.

annekainicUSDS · 2018-07-03T18:20:00Z

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

+
+2. Install peer dependencies:
+```bash
+npm install --save-dev @department-of-veterans-affairs/formation


We no longer need formation, so you can remove this line!

I was wondering about that one!

annekainicUSDS · 2018-07-03T18:20:15Z

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

+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.


yes I think so

annekainicUSDS · 2018-07-03T18:23:30Z

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

+
+### 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 and npm to develop using the US Forms System. For more information, including installation instructions, see the [Node.js website](https://nodejs.org).


I'm not totally positive about this, but I think they need at least Node version 8 in order for this to work properly. I don't know if there's a specific version of npm needed in order for this to work, but I'm using 5.6.0 locally, so I might recommend at least having version 5 or great installed? @dmethvin-gov do you know more about this?

Dave says 8 is right, so that's what I documented. 👍

bernars-usa · 2018-07-05T18:37:04Z

Thanks so much for the reviews on this. I'm going to merge it into #90 now. If there's additional feedback, I'll incorporate it in a subsequent PR.

bernars-usa added 12 commits June 20, 2018 11:04

Getting started topics and links in readmes

99dabfe

Remove old Getting Started topic

7e1d785

Getting Started short descriptions

a6b6162

Map shortdescs

7083cc5

Main content for starter app topic

a5f1e12

Structure for existing app topic

d6ebe8d

Installation instructions

38c32c9

Instructions for required files

e328112

Missing topic

dd2b2e6

A little more about the routes file

f1d0385

Spacing, does it matter?

f48aae1

Apparently it's bash

2bc4870

bernars-usa commented Jun 20, 2018

View reviewed changes

bernars-usa mentioned this pull request Jun 20, 2018

Organize docs in docs folder #86

Closed

bernars-usa self-assigned this Jun 20, 2018

annekainicUSDS reviewed Jun 21, 2018

View reviewed changes

bernars-usa commented Jun 21, 2018

View reviewed changes

Standardize on 'US Forms System'

7272c08

bernars-usa added 2 commits June 22, 2018 09:14

Merge forms-docs into getting-started

64444c1

Add a link to React tutorial, weird tweak to app.js description?

d92a508

bernars-usa commented Jun 22, 2018

View reviewed changes

Merge forms docs into getting-started

301761f

bernars-usa mentioned this pull request Jun 28, 2018

[Ready for review]: About the schemaform code (docs) #112

Merged

Add prereqs

3315bf8

bernars-usa added 2 commits June 29, 2018 16:08

Move this list into a separate file so it can be referenced in both o…

21cf015

…f the others

Link to the new file at the top of the other two

f8d03cc

bernars-usa added 2 commits July 2, 2018 11:57

Revised 'Creating a new app' with a lot more instructions, including …

306c08c

…cloning

Add links to Getting Started articles

ce5cac4

React link is elsewhere now

260b607

bernars-usa requested review from annekainicUSDS and dmethvin-gov July 2, 2018 17:56

Someday I'll learn Markdown

7ec572f

annekainicUSDS reviewed Jul 3, 2018

View reviewed changes

bernars-usa added 6 commits July 5, 2018 10:37

Merge forms-docs into getting-started

d4d7361

Merge forms-docs into getting-started

c52261a

Talk about how to view output

b39fd15

Formation not required

5467b2c

Minimum node.js 8.0.0

aa68e4c

Link to USWDS for funsies

a56de80

bernars-usa merged commit 736036e into forms-docs Jul 5, 2018

bernars-usa deleted the getting-started branch July 5, 2018 18:37

This was referenced Jul 9, 2018

[Ready for review] Forms System Documentation #90

Merged

Enhance Documentation for Starter App #79

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Docs: Getting Started content for Documentation #96

Docs: Getting Started content for Documentation #96

bernars-usa commented Jun 20, 2018

bernars-usa Jun 20, 2018

annekainicUSDS Jun 21, 2018

bernars-usa Jun 21, 2018

annekainicUSDS left a comment

annekainicUSDS Jun 21, 2018

bernars-usa Jun 21, 2018

bernars-usa Jun 21, 2018

annekainicUSDS Jun 21, 2018

bernars-usa Jun 21, 2018

annekainicUSDS Jun 21, 2018

annekainicUSDS Jun 21, 2018

annekainicUSDS Jun 21, 2018

bernars-usa Jun 21, 2018

bernars-usa commented Jun 21, 2018

bernars-usa Jun 22, 2018

annekainicUSDS Jul 3, 2018

bernars-usa Jun 22, 2018

bernars-usa commented Jun 22, 2018

bernars-usa commented Jun 29, 2018

bernars-usa commented Jul 2, 2018

annekainicUSDS left a comment

annekainicUSDS Jul 3, 2018

annekainicUSDS Jul 3, 2018

bernars-usa Jul 5, 2018

annekainicUSDS Jul 3, 2018

annekainicUSDS Jul 3, 2018

bernars-usa Jul 5, 2018

bernars-usa commented Jul 5, 2018


		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."


		### [Installing the library in an existing application](getting-started/installing-the-library-in-an-existing-application.md)

		If your existing application has a web server to run the app locally, you can install the US Forms System Library in that app.

		@@ -0,0 +1,35 @@
		# Installing the library in an existing application

		If your existing application has a web server to run the app locally, you can install the US Forms System Library in that app.


		The US Forms System Starter App creates the initial files, configuration, build process, and web server you need to start building your form immediately.

		For more information, including app installation instructions, see the [US Forms System Starter App README](https://github.com/usds/us-forms-system-starter-app#us-forms-system-starter-app).


		### 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. For more information about React apps, see the [React project's Hello World tutorial](https://reactjs.org/docs/hello-world.html).


		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`.


		### 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 and npm to develop using the US Forms System. For more information, including installation instructions, see the [Node.js website](https://nodejs.org).

Docs: Getting Started content for Documentation #96

Docs: Getting Started content for Documentation #96

Conversation

bernars-usa commented Jun 20, 2018

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

annekainicUSDS left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

bernars-usa commented Jun 21, 2018

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

bernars-usa commented Jun 22, 2018

bernars-usa commented Jun 29, 2018

bernars-usa commented Jul 2, 2018

annekainicUSDS left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

bernars-usa commented Jul 5, 2018