Enhance Documentation for Starter App

[ju-liem]

As @jcmeloni-usds used the starter app to create a first pass at the H2A superform, she noted that additional examples for the form config and information for getting started with the starter app would make it (even) more useful (than it already is).

@jcmeloni-usds, can you add some of your thoughts/ideas to this issue when you have time?

[bernars-usa]

I'd be thrilled to incorporate thoughts and ideas for doc updates.

[jcmeloni-usds]

Apologies in advance for this coming out generally as stream-of-consciousness but here we go:

• I think it's super important that we emphasize some familiarity ahead of time is needed with your system from a development standpoint. By this I mean something like "Must be familiar with CLI, Node, npm, build systems". (puts on eng manager hat) To me, this is a minimal requirement for all front-end developers using modern tools, and is a reasonable starting point otherwise we'll be dealing w/ help requests for all the different system nuances around getting npm etc set up on one's machine.
  • that being said, on my fresh ubuntu machine I had zero issues installing node and npm and getting the starter app started -- maybe 7 minutes total and that includes a detour around ubuntu's default node installation to get to the latest version (this is an ubuntu 16.04 issue not a USFS issue)
  • Yes, that all means that the "you must be familiar with..." list is going to be longer than the "how to start this" list. ha.
• We should finalize if we're going to tell people to fork or clone. I think we settled on clone because that makes sense with how people will actually use it (e.g. not committing back to usfs starter app), but we may need to wait a little bit until the usfs npm package is poublished and the usfs starter app is rejiggered to import that rather than how it's working now
• Beyond installation, I generally started working w/ form.js this way -- which is NOT how most people would do it, I don't think, because they wouldn't know where all the vets.gov stuff lives. Also, this was a super stupid way for me to get started and I should have known better
  • had the usfs documentation up
  • had the mozilla rjsf documentation up
  • had the 1010EZ form in front of me
  • had the js for the 1010EZ in front of me
  • tried to match what I wanted to use with what I was seeing in the 1010EZ with what I was looking for in the definitions files
  • got frustrated and reminded myself just to start small and build up from there and not try to do it the "right" way by reusing components and creating definitions for commonly-used things
• When I got out of my own way and did it the longer way to at least get something on the screen, my questions were around the following...while I could figure them all out, they seemed to be of the low-hanging-fruit type that it might be nice just to tell people so they don't get bogged down in their own brains (or maybe that's just me!)
  • where should I change the grid type
  • where should I change the font/size
  • what's the best way to specify input field sizes
  • how do I get the custom validation message to kick instead of the default (e.g. does it require custom valdation method to use custom validation message?)
  • should I be using the updown widget from mozilla, or something else, for integers
  • what's the best way to use definition files (alternately, what are best practices for creating definitions?)
• It might also be a nice thing to add a basic submit action example, e.g. print out json response or something, just so people running the starter app could see something end to end right out of the box.

[jcmeloni-usds]

@ju-liem Back to you for prioritization and discussion w/ @bernars-usa

[dmethvin-gov]

"Must be familiar with CLI, Node, npm, build systems."

Completely agree here. You'll need to add React as well. This section could contain a bullet list of things you need, along with links, but keeping it brief will prevent us from having to maintain a big "how to learn teh JavaScripts" tutorial that newcomers will constantly want to expand every time they have a problem setting up their environment.

We should finalize if we're going to tell people to fork or clone

I thought about this some more. At the end of the setup, people want a repo that represents the name of their real us-forms-system project. Since the sample app is very skeletal and their real app will not be a fork that we'd want to merge back into the sample app, a clone seems better. So we could give them the steps to clone the sample, edit the basics in package.json, re-set the git remote origin to their own repo, and push it with a descriptive name.

while I could figure them all out, they seemed to be of the low-hanging-fruit type that it might be nice just to tell people so they don't get bogged down in their own brains

I think a "How do I..." in the docs would be great! Also note that the answers may include using or doing things outside us-forms-system. The React ecosystem already has a lot of components so we should try to use them when possible rather than widening the scope of this project to include them. Especially at the beginning!

[bernars-usa]

I thought about this some more. At the end of the setup, people want a repo that represents the name of their real us-forms-system project. Since the sample app is very skeletal and their real app will not be a fork that we'd want to merge back into the sample app, a clone seems better. So we could give them the steps to clone the sample, edit the basics in package.json, re-set the git remote origin to their own repo, and push it with a descriptive name.

I also thought about this some more, and am going back to wondering about forking. While users won't be contributing back, are there updates we'll want users to get from this repo periodically, or is that aspect being covered with releases (git tags)? If users configure a remote for the fork (https://help.github.com/articles/configuring-a-remote-for-a-fork/), they'll be able to stay in sync (https://help.github.com/articles/syncing-a-fork/).

[dmethvin-gov]

We should migrate this ticket to the us-forms-system-starter-app repo.

In some future perfect thing we could have a create-forms-app command like create-react-app and that could ask some questions to get everything set up just right. For now I think cloning and a step-by-step for what to change in package.json would be fine.

[bernars-usa]

We should migrate this ticket to the us-forms-system-starter-app repo.

I'm planning on putting the instructions in this repo for now and linking to them from us-forms-system-starter-app. I can't think of a good way to segregate the information between the repos, so keeping it all together in one place seems best for now.

[dmethvin-gov]

Makes sense! 👍

[bernars-usa]

I think this information is well in hand given #149 and #96. Everyone ok closing?

[dmethvin-gov]

Yep, we've got specific docs tasks in progress on other tickets and PRs.