Improve coverage of question style guide

docs/style_guide/question_style_exit_screen.md

@@ -0,0 +1,74 @@
+---
+id: question_style_exit_screen
+title: Build-in offramps (exit screens)
+sidebar_label: Build-in offramps
+slug: question_style_exit_screen
+---
+
+## Every interview needs to make a choice
+
+If your interview handles every situation, you probably don't need an exit screen.
+But in the real world, your interview needs to make choices.
+
+For example: CourtFormsOnline's adult name change interview only handles adult name changes.
+If the user is under 18, they are screened out. A separate interview handles minor name
+changes.
+
+Making choices about which situations your interview will handle allows you to release
+the interview into the world.
+
+## When to use an exit screen
+
+As part of the introductory screens of your interview,
+you should explain any rules or limits that would prevent a user
+from qualifying to use your interview.
+
+In many cases, it can also help to explicitly ask qualifying
+questions.
+
+### What to include in an exit screen
+
+1. A clear message that the person does not qualify.
+2. Consider a visual indicator, such as a raised hand, a stop sign, a warning triangle.
+3. Explain why the person does not qualify. Include specific information related to 
+   the responses that they gave.
+4. Include a next step, such as starting the interview over or visiting a website with an alternative
+   solution.
+
+### A "hard" exit screen
+
+"Hard" exit screens stop the user from continuing. They should
+always offer an alternative choice.
+
+Consider offering a choice that allows the user to revise their response
+or start the interview over.
+
+This exit screen in MADE appears when the user chooses a common
+housing-related problem that is **not** an eviction:
+
+![](./assets/example_exit_made_use_uptocode.png)
+
+This exit screen in a name change interview appears when the user
+wants to change their name, but the form does not handle their situation:
+
+![](./assets/example_exit_name_change.png)
+
+### A "soft" exit screen
+
+This exit screen in MADE appears when the tenant is trying to stop
+an eviction but the eviction hasn't been filed in court yet:
+
+![](./assets/example_exit_case_not_ready.png)
+
+Soft exit screens are a good option to slow the user down and make sure
+that they are making the right choice.
+
+## Should you let the user continue instead?
+
+An exit screen enforces the choices that the developer made when deciding
+the scope of the interview. It can also enforce clear legal rules or
+business logic.
+
+When someone uses a paper form, they can turn in something that isn't
+legally sufficient. But when they use a computer tool, they usually
+expect more enforcement.

docs/style_guide/question_style_help_your_user.md

@@ -36,6 +36,11 @@ Diagrams and videos can explain information much more clearly than text:
 1. make use of timelines, charts, and similar visual aids if needed to help a
    user understand a larger process
 
+Example: a diagram of a form with the place that the tenant's information
+will appear highlighted.
+
+![](./assets/example_picture_of_form.png)
+
 ## Keep page content short and actionable
 
 A guided interview is **not** an appropriate place to educate your user

docs/style_guide/question_style_navigation.md

@@ -0,0 +1,100 @@
+---
+id: question_style_navigation
+title: Show progress
+sidebar_label: Show progress
+slug: question_navigation
+---
+
+## Add navigation
+
+All but the shortest interviews should also include some way to tell the user
+how long the process will take and where they are in the process.
+
+Use navigation sections with clear titles that give the user these cues.
+
+For example, consider the navigation for a hypothetical form that allows a user
+to request the court to waive fees:
+
+1. Introduction
+1. Can I get a fee waiver?
+1. My name
+1. My claim/defenses
+1. My information
+1. Information about the other side
+1. Review
+1. Signature
+1. Download and next steps
+
+In a HotDocs interview, these sections will correspond 1 to 1 to pages and
+titles of pages in the interview. In Docassemble, you must add these sections
+separately.
+
+In a Docassemble interview, consider using the sections to allow the user to
+edit and review their answers as they use the interview. This requires
+additional work but may build the user's confidence as they use your website.
+
+Example of Docassemble's standard navigation:
+
+![](./assets/example_navigation_guardianship.png)
+
+A custom navigation style mimicing Google's material UI:
+
+![](./assets/example_navigation_uptocode.png)
+
+## Use signposting on longer interviews
+
+On longer interviews, it may not be enough to use the sections on the left
+to orient the user.
+
+One way to orient the user is to use "signposts". Signposts are screens
+that do not ask any questions, but instead tell the user what questions are
+coming next.
+
+Consider adding signposts:
+
+1. on longer interviews to remind the user that they are making progress
+1. to tell the user when they are about to ask questions about a very different topic
+1. to give the user a chance to reflect on the answers that they gave in another
+   long section and to correct any mistakes before continuing down a long new branch
+   of questions
+1. when the user may be getting tired, especially to let them know that they are
+   close to finishing
+
+Example mid-interview signpost to encourage the user. This signpost also summarizes the work that the user
+just completed and gives them a preview of the results.
+
+![You have a defense!](./assets/example_signpost_you_have_a_defense.png)
+
+Example signpost towards the end of the interview. Sections are of variable length in this interview, so a signpost here
+helps convey to the user that the end is approaching,
+even though there are a few small sections left.
+
+![Almost done! Just a few questions left.](./assets/example_signpost_almost_done.png)
+
+Example signpost at the beginning of a new, longer section to help explain a switch in
+the style and information required for the upcoming questions:
+![This section will ask about claims and counterclaims.](./assets/example_signpost_mini_introduction.png)
+
+On very short interviews, signposts may not be needed.
+
+## Review progress
+
+In all but the shortest interviews, the user will find it very cumbersome
+to use the "undo" or "start over" button to fix a mistake in their interview.
+
+CourtFormsOnline's current style encourages the author to use an in-line
+review screen that always appears during the course of the interview. This may be
+unecessary in a very short interview with linear logic.
+
+Review screens can be very time consuming to build and maintain because editing
+one response can set off a chain reaction of dependent changes. We do not have data
+yet on how common edits are, but we suspect the most common edits focus on typos
+in names, addresses, and so on, rather than substantive questions. We encourage
+authors to focus on these most likely to change and easiest
+to implement review screens. You can let the user know that they have to start over
+for certain changes. For example: a change that triggers a whole new series of questions.
+
+Example of a comprehensive review screen showing accordion sections. Note that each area of the review screen
+summarizes the answers the user has already given, and has an edit button once per each "screen" of the interview:
+
+![Review screen showing accordion sections and "edit" button](./assets/example_review_screen.png)

docs/style_guide/question_style_structure.md

@@ -31,6 +31,41 @@ Your interview should start with a short screen that identifies the interview,
 gives the user context, and tells them anything that they need to have in front
 of them before they begin.
 
+#### Separating the terms of use from the "before you start" information
+
+CourtFormsOnline.org's style is to use two intro screens:
+
+1. A general-purpose intro screen that just states the name of the form
+   and includes a terms of use checkbox.
+2. A tailored intro screen that helps the user know what to expect and what they need
+   to know.
+
+  ![](./assets/example_intro_terms_of_use.png)
+  ![](./assets/example_intro_before_you_start.png)
+
+#### Make the user feel welcome, but don't say "welcome!"
+
+**Welcome** is a cliche that is best to avoid on an introductory screen.
+If the user may be particularly uncomfortable, affirmations can be appropriate!
+
+Keep them actionable and focused on what might make the user nervous to complete
+the interview.
+
+[Read more about avoiding the word "welcome"](https://www.nngroup.com/articles/top-ten-guidelines-for-homepage-usability/)
+
+Example affirmation in an interview supporting domestic violence survivors.
+This appears just before the emotionally hardest part of the interview, the
+affidavit where the survivor describes the abuse:
+
+![Example affirmation in an interview supporting domestic violence survivors](./assets/example_affirmation_209a.png)
+
+Example affirmation in a tool to help tenants sue their landlord. This
+comes at the beginning of the interview to help tenants overcome
+worries that their landlord will unfairly retaliate against them
+for reporting housing problems:
+
+![Example affirmation from a tool to sue your landlord](./assets/example_you_can_do_this_uptocode.png)
+
 ### Keep screening questions early in the interview
 
 Screening questions are questions that tell the user if they are using the right
@@ -83,56 +118,6 @@ have:
 1. a document they can print and take with them that tells them what to do after
    they have finished using the website, which we call a "next steps" document.
 
-## Add navigation
-
-All but the shortest interviews should also include some way to tell the user
-how long the process will take and where they are in the process.
-
-Use navigation sections with clear titles that give the user these cues.
-
-For example, consider the navigation for a hypothetical form that allows a user
-to request the court to waive fees:
-
-1. Introduction
-1. Can I get a fee waiver?
-1. My name
-1. My claim/defenses
-1. My information
-1. Information about the other side
-1. Review
-1. Signature
-1. Download and next steps
-
-In a HotDocs interview, these sections will correspond 1 to 1 to pages and
-titles of pages in the interview. In Docassemble, you must add these sections
-separately.
-
-In a Docassemble interview, consider using the sections to allow the user to
-edit and review their answers as they use the interview. This requires
-additional work but may build the user's confidence as they use your website.
-
-## Use signposting on longer interviews
-
-On longer interviews, it may not be enough to use the sections on the left
-to orient the user.
-
-One way to orient the user is to use "signposts". Signposts are screens
-that do not ask any questions, but instead tell the user what questions are
-coming next.
-
-Consider adding signposts:
-
-1. on longer interviews to remind the user that they are making progress
-1. to tell the user when they are about to ask questions about a very different topic
-1. to give the user a chance to reflect on the answers that they gave in another
-   long section and to correct any mistakes before continuing down a long new branch
-   of questions
-1. when the user may be getting tired, especially to let them know that they are
-   close to finishing
-
-
-On very short interviews, signposts may not be needed.
-
 ## Read more
 
-[Get the questions in order](https://service-manual.nhs.uk/content/how-to-write-good-questions-for-forms/get-the-questions-into-order)
+[Get the questions in order](https://service-manual.nhs.uk/content/how-to-write-good-questions-for-forms/get-the-questions-into-order)

sidebars.js

@@ -59,6 +59,8 @@ module.exports = {
                 // 'style_guide/question_style_sensitivities',
                 'style_guide/style_guide_readability',
                 'style_guide/question_style_structure',
+                'style_guide/question_style_exit_screen',
+                'style_guide/question_style_navigation',
                 'style_guide/question_style_organize_fields',
                 'style_guide/question_style_help_your_user',
                 'style_guide/style_guide_formatting',