[Ready for review] Edit conceptual info #187
Conversation
| @@ -12,6 +12,6 @@ | |||
| - [Available widgets](building-a-form/available-widgets.md) | |||
| - [Common definitions](building-a-form/common-definitions.md) | |||
| - [Common patterns for building forms](building-a-form/common-patterns-for-building-forms.md) | |||
| - [Creating custom fields and widgets](building-a-form/creating-custom-fields-and-widgets.md) | |||
| - [How the library works](how-the-library-works/README.md) | |||
There was a problem hiding this comment.
One thought about removing this topic on "How the library works": I was imagining other topics could go in here in the future. For example, in order to address this ticket, I was going to add a topic on how USFS uses Redux, and I assumed it would fit into a "How the library works" category, but curious on your thoughts here.
There was a problem hiding this comment.
I can help think through where to put that information. We really need these three different maps (sections) for these distinct audiences:
- People just introducing themselves to the library (Getting started)
- People who have everything set up and are building basic forms with no customizations (Building a form)
- People who are not only building forms, but building customizations on top of the library (Customizing the library)
These are what equate to "Beginner, Intermediate, and Advanced." Users do not self-identify into those groups accurately, so you have to be very explicit about the use cases.
There was a problem hiding this comment.
I guess to me "Customizing the library" feels like a topic within a larger category of advanced things someone might need to know about potentially. For example, I can foresee future topics within an advanced category related to adding features for prefill and save in progress or how the state model works.
There was a problem hiding this comment.
I can foresee future topics within an advanced category related to adding features for prefill and save in progress or how the state model works.
Definitely. We're eventually going to want to break up "Building a form" more, depending on future improvements to the library.
There was a problem hiding this comment.
Okay that makes sense! Sounds good :)
| @@ -1,5 +1,7 @@ | |||
| # Creating custom fields and widgets | |||
|
|
|||
| You can customize the base library in order to build web-based forms using React and the JSON Schema standard. | |||
There was a problem hiding this comment.
I think perhaps the more specific use case here is: "You can customize the base library in order to satisfy the unique requirements of your particular form." Or something like that. Not that it just lets you build web-based forms, because the base library lets you do that, but so that you can do specific things that aren't required in the base library. It's a little reductive, but at least it's more accurate. Let me know if that makes sense!
There was a problem hiding this comment.
Yeah, thank you, I tried to bulk this up but was going to ask you for more info. This is great!
|
Ok, this is ready for review! I moved some things around to get the new "Customizing the library" map topic, and did a copy edit of the new content @annekainicUSDS added (you can see that on it's own in 39c9b7c). Let me know if you have any questions! |
bernars-usa
changed the title
| @@ -8,7 +10,7 @@ | |||
|
|
|||
| ### How us-forms-system uses rjsf | |||
|
|
|||
| The us-forms-system code uses rjsf to render form fields, but it builds a scaffolding on top of it to support multi-page forms and our common form patterns. Additionally, us-forms-system uses rjsf to create a form configuration spec that allows devs to specify the structure of one of our multi-page forms. | |||
| The us-forms-system code uses rjsf to render form fields, but it builds a scaffolding on top of it to support multi-page forms and our common form patterns. Additionally, us-forms-system uses rjsf to create a form configuration spec that allows developers to specify the structure of a multi-page form. | |||
There was a problem hiding this comment.
The "our common form patterns" supposes a particular use case so I'd pull out "our".
This is a branch off of #186, which is where @annekainicUSDS took a huge step in improving the conceptual information about the library. This PR just fine-tunes that work a bit.