Revise structure for easier skimming #1939
Conversation
There was a problem hiding this comment.
The Entities Sheet section with the expanded create/update/conditional examples looks great!
Additional/restructuring of label hints and notes look good!
I noticed that the entity ID was referred to as the "system ID" in a few places and I think I like that framing. We could use the phrase "system ID" in the "Structure of an Entity" section, too.
I also noticed some of the "XLSForm" headers got changed into more informative labels but now it's not consistent between each snippet. Some still just say "XLSForm", some say "XLSForm: description of example" and some just have a description of the example.
The small titles of the tables are also inconsistent, with some having just the name of the sheet and some having a longer description of the example. I probably started this inconsistency with my giving up on labeling the original examples part way through!
|
|
||
| * We recommend using :doc:`concat </form-logic/>` with fields from your form. | ||
| * The label can be blank if the form updates the Entity but does not change the label. | ||
| * You can use the label to show status information about the Entity, including using emoji like ✅ or ⚪️. |
There was a problem hiding this comment.
We should add another bullet point. Maybe it should be longer/explain this more, but it should at least get at the fact that there isn't a uniqueness constraint on the label, it's mainly just for display purposes.
- The label does not need to be unique.
There was a problem hiding this comment.
Are there any other quick tips about picking which fields to put in your label formula?
|
|
||
| .. rubric:: XLSForm | ||
| .. csv-table:: entities |
There was a problem hiding this comment.
Some of the snippets say "entities" or "survey" while some say something longer like
Example
surveysheet withsave_tocolumn filled in with property names for certain field
Can we make them consistent?
Should we make them more explicit, like "survey sheet" instead of "survey"?
|
|
||
| orders, "Approved: ${existing_order}", ${existing_order}, ${status} = 'approved' | ||
|
|
||
| Saving the Entity ID in a Registration Form | ||
| ___________________________________________ |
There was a problem hiding this comment.
A few lines below, there's a .. rubric:: XLSForm. I noticed some of these in the examples above got removed, should the rest also be removed/renamed to something more informative?
Co-authored-by: Kathleen Tuite <[email protected]>
My primary goals were to:
While working on those I made light edits that I hope help with clarity.
@ktuite, please do push back on changes you don't think are improvements. Also happy to merge and then see another PR from you making further changes.