More info on good practices for fields

docs/style_guide/question_style_organize_fields.md

@@ -10,13 +10,17 @@ you need to apply your own restraint to make sure that questions are asked
 at a pace that your user can answer easily.
 
 Screen breaks can act as a signpost that tells the user that you have finished
-one topic and are ready to move on to another.
+one topic and are ready to move on to another. Too many screen breaks can add
+delay and reduce the user's satisfaction with the interview.
 
 ## First, organize fields into topics
 
 Before you work on a screen, follow the guidance about [structuring your interview](question_style_structure.md#group-similar-questions-together-by-topic)
 to make sure your fields are grouped into logical topics.
 
+Each page should only contain related fields that are described
+accurately by the page's heading.
+
 ## Ask the most restrictive questions on the screen first
 
 If a response to an early question rules out the need to ask a follow-up,
@@ -37,7 +41,7 @@ How old is John?
 
 ## Ask for only a few fields on each screen
 
-A good rule of thumb is to ask for no more than about 5 pieces of information on
+A good practice is to ask for no more than about 5 pieces of information on
 each screen. Users seldom mind answering a lot of simple questions one screen at 
 a time. A long screen that requires scrolling from the heading or instructions
 to each fill-in field can slow your user down more than clicking the "next"
@@ -50,6 +54,35 @@ when you are asking the user for a single piece of information, like their
 address, but ask them to provide it in multiple fields, like street address,
 postal code, and city.
 
+### The "doorway effect"
+
+Have you ever forgotten what you were looking for when you get up to go 
+into a new room? This is often called "the doorway effect", and it's a real
+phenomenon of memory.
+
+Adding a new screen can be like passing through a doorway for the user.
+Make sure that when you add a new screen, the user isn't forced to remember
+information that they just provided on the previous screen.
+
+This is especially important for open-ended questions that might be related.
+
+### Should I ask for just one field per screen?
+
+Some popular guided interview platforms, like A2JAuthor, only allow authors
+to place one question on each screen.
+
+Others, like HotDocs, can be formatted like a busy paper form, with dozens of fields
+on a screen in multiple columns.
+
+Docassemble is mobile first, and in mobile design of surveys, studies show that the best design
+to reduce interview time for the user and to reduce fatigue emphasizes "scrolling" (multiple
+fields per screen) over "paging" (one question per screen).
+
+Our magic number "5" fields per screen is a good rule to start with.
+
+* [Surveymonkey on paging vs scrolling](https://www.surveymonkey.com/curiosity/pros-cons-of-scrolling-and-multiple-pages-in-surveys/)
+* See also Antoun, C., Katz, J., Argueta, J., & Wang, L. (2017). Design Heuristics for Effective Smartphone Questionnaires. Social Science Computer Review, 36(5), 557-574. https://doi.org/10.1177/0894439317727072 (Original work published 2018)
+
 ## Where possible, ask short follow-up questions on the same screen
 
 Use a field on the same screen to ask your user for follow-up information when:

docs/style_guide/style_guide_formatting.md

@@ -14,9 +14,9 @@ Users [tend to scan text](https://www.nngroup.com/articles/f-shaped-pattern-read
 
 If you are tempted to write a large amount of text on the screen, consider:
 
-1. Using a link
 1. Adding a [progressive disclosure
 element](../coding_style/yaml_interface.md) that lets a user click to read more.
+1. Using a link (but keep in mind that getting back to the interview after clicking a link can be challenging for many users, especially on a mobile device)
 
 Your user is very goal oriented when using a legal form. They rarely come to
 a form to be educated about the law. Help them get to the end as quickly
@@ -35,7 +35,7 @@ For accessiblity reasons, headings should always follow in order from H1, to H2,
 and then H3 and so on. Do not skip a level. In docassemble, the question title
 is H1, so you should stick with H2 and below.
 
-#### Use sentence case, not Title Case for page headings
+#### Use sentence case, not Title Case for page headings and field labels {#sentence-case}
 
 `Sentence case` only capitalizes the first word while `Title Case` capitalizes
 each word in a sentence. `Sentence case` is easier to read and most websites use
@@ -44,6 +44,37 @@ it.
 #### Keep headings short {#short-headings}
 A heading should only be about one line of text on the screen.
 
+### Keep field labels short {#keep-field-labels-short}
+
+Rather than a long question or instruction, like "What is your name?" or 
+"Write your name below", prefer a label like "Name".
+
+Writing a long, descriptive prompt that includes obvious directions is a common
+mistake made by new developers. Short labels are usually easier and faster to process 
+than long questions.
+
+Most prompts (the text that is to the left of the field in a normal Docassemble interview)
+should stay on one line.
+
+#### Omit obvious instruction verbs like "write" or "enter"
+
+Verbs like "enter", "write", or "list" are unnecessary in a field label.
+
+#### Consider labeling optional fields {#label-optional}
+
+Docassemble adds a red asterisk (`*`) next to required fields, but when most
+fields on the screen are required, it may be helpful to label optional fields instead.
+This is especially useful when the user is presented an area field to enter a potentially
+long explanation.
+
+Use a short parenthetical (optional) at the end of the field label.
+
+Example:
+
+```
+Explain why you need extra time (optional)
+```
+
 ### Use lists and bullets to group information
 
 Use lists and bullets to make it easy for your user to understand the information
@@ -74,7 +105,7 @@ keep going.
 * [Australian style guide on tables](https://www.stylemanual.gov.au/structuring-content/tables)
 
 
-## Only use all capital letters for acronyms and initialisms
+## Only use all capital letters for acronyms and initialisms {#use-capital-initialisms}
 
 Sentences written with all capital letters are harder to read. Use them
 only when the word is always written in all capital letters. Do not use
@@ -83,7 +114,7 @@ capital letters for emphasis.
 For example, the Department of Children and Families (DCF), Transitional
 Assistance for Families and Dependent Children (TAFDC).
 
-## Use bold for emphasis. Avoid underlines, italics, or all capital letters
+## Use bold for emphasis. Avoid underlines, italics, or all capital letters {#emphasize-with-bold}
 
 Bold text is easy to identify and read.
 
@@ -99,4 +130,9 @@ Your guided interview platform may already make a lot of choices for you that af
 and contrast. When you customize or add a lot of text, though, you need to keep them in mind yourself.
 
 [The Non-designer's Design Book](https://www.amazon.com/Non-Designers-Design-Book-4th/dp/0133966151/) is
-a terrific introduction to basic design concepts.
+a terrific introduction to basic design concepts.
+
+## Read more
+
+* [Adobe's style guide for form labels](https://spectrum.adobe.com/page/field-label/)
+* [Nielsen Norman Group's recommendations on form design](https://www.nngroup.com/articles/web-form-design/)