136 строки
7.8 KiB
Markdown
136 строки
7.8 KiB
Markdown
# Introduction
|
||
|
||
The HAX Playbook is an interactive tool for generating interaction scenarios to test when designing
|
||
user-facing AI systems.
|
||
|
||
A default survey about designing an AI system is included in this repository. It provides a
|
||
demonstration of the features supported by the web app.
|
||
|
||
The web app's features include fully customizable contextual help cards, salutation message,
|
||
farewell message, and a list of tasks based on survey results. All of these components are read
|
||
from a JSON file. See the Extension section for more details.
|
||
|
||
# Getting started
|
||
|
||
To run the app, open a terminal in the root directory of the repository and run:
|
||
|
||
```
|
||
$> npm install
|
||
$> npm start
|
||
```
|
||
|
||
# Extending survey functionality
|
||
|
||
The survey and textual content are defined in JSON files. To add your own content, modify the JSON files
|
||
as instructed below.
|
||
|
||
## Survey
|
||
|
||
The survey is defined in `src/data/survey.json`. SurveyJS is the library used to render
|
||
the survey. To create your own survey, use the [survey creator](https://surveyjs.io/create-survey) on the SurveyJS website.
|
||
|
||
To export the survey you've created, click on the `JSON Editor` tab and copy the contents, then paste into `src/data/survey.json`.
|
||
|
||
### Survey guidelines
|
||
To make sure your survey is supported, please adhere to the following guidelines:
|
||
- Only use the radio group, dropdown, and boolean survey components.
|
||
- Specify a `name` for each question. A default name like `question1` will be provided automatically in the SurveyJS builder. It's better to use a descriptive name to make the generated `content.json` file more readable.
|
||
|
||
### How to create a cascading survey
|
||
The survey included with the HAX Playbook has a cascading-question effect, causing new questions to appear when the user selects an answer.
|
||
Cascading questions are implemented by configuring the visibility rules for questions in the survey.
|
||
The visibility rules can be configured in the SurveyJS builder or in the JSON file.
|
||
To configure visibility in the SurveyJS builder, select the question to modify, then select the `Visible if` rule in the `Logic` section of the `Properties` toolbar.
|
||
A cascading-question effect is implemented by using the rule `{previous_question_name} is not empty`.
|
||
Effectively, this rule says, "if an answer has been selected for the previous question, then show this question."
|
||
|
||
|
||
## Textual content
|
||
|
||
All of the content outside of the survey itself is defined in `src/data/content.json`. This content is used to enrich the user experience
|
||
by providing an introduction, instructions for each survey question, contextual help for each choice, and tasks for each choice. HTML is supported inside each component.
|
||
|
||
### Generating a starter file
|
||
A starter content.json file can be generated from a survey.json file. The starter file will contain a skeleton of the data with empty strings
|
||
ready for you to fill in. There are two options to generate it.
|
||
|
||
#### Script
|
||
To use the script, open a terminal at the repository's root directory and do:
|
||
|
||
```
|
||
$> node scripts/generate.js <path_to_survey.json> <output_file_name>
|
||
```
|
||
|
||
#### API
|
||
If you can't run node locally, there is also an API available. Send your `survey.json` in the request body.
|
||
|
||
`POST https://surveymeta.azurewebsites.net/api/generate`
|
||
|
||
### Explanation of properties in content.json
|
||
|
||
#### Top-level properties
|
||
- introduction: The message displayed before the survey begins. This is optional.
|
||
- surveyInstructions: The message to display above the survey. This property has a `title` and a `message`.
|
||
- taskInstructions: The message to display above the list of tasks. This property also has a `title` and a `message`.
|
||
|
||
#### Question properties
|
||
- name: The name of the question. Must match the question name in `survey.json`.
|
||
- category: The category for the question. Tasks will be consolidated into sections by category.
|
||
|
||
#### Choice properties
|
||
- name: The name of the choice. Must match the choice name in `survey.json`.
|
||
- definition: A message that will appear below the survey choice, along with the ? button.
|
||
- examples: Contains an array of examples. These examples are shown in the help pop-up when the ? button is clicked for that choice.
|
||
- taskCard: Defines the tasks corresponding to the question. Tasks are shown in the survey results page.
|
||
|
||
#### Example properties
|
||
- name: The title of the example. Appears in the help dialog as a heading.
|
||
- details: The message for the example. HTML is supported.
|
||
- visibleIf: A logic expression that controls whether or not this example is visible. This can be used to provide contextual examples based on the user's choices in the survey. [Syntax documentation](#syntax-for-visibleif-logic)
|
||
|
||
#### Task card properties
|
||
- message: A message to show for the entire group of tasks.
|
||
- tasks: An array of tasks.
|
||
|
||
#### Task properties
|
||
- name: The title of the task.
|
||
- details: The message for to the task. HTML is supported.
|
||
- visibleIf: A logic expression that controls whether or not this task is visible. This can be used to provide contextual tasks based on the user's choices in the survey. [Syntax documentation](#syntax-for-visibleif-logic)
|
||
|
||
### Syntax for visibleIf logic
|
||
SurveyJS includes a robust domain-specific language for controlling the flow of the survey. See https://surveyjs.io/Documentation/Library#conditions for the official documentation and examples. Configuring logic in the [survey creator](https://surveyjs.io/create-survey) is a good option if you don't want to handwrite code.
|
||
|
||
Here are some basic examples to get you started.
|
||
- Check if the user selected a certain choice: `"visibleIf": "{questionName} = 'choice'"`
|
||
- Check if the user **did not** select a choice: `"visibleIf": "{questionName} <> 'choice'"`
|
||
|
||
# Contributing
|
||
|
||
Check [CONTRIBUTING](CONTRIBUTING.md) page.
|
||
|
||
# Research and acknowledgements
|
||
This project materializes and implements ideas from ongoing research on Human-AI interaction. Here is a list of development and research contributors:
|
||
|
||
**Current Contributors**: [Nicholas King](https://www.nickbking.com/), [Jingya Chen](https://www.jingyachen.net/), [Kathleen Walker](https://www.linkedin.com/in/kathleenedits/), [Mihaela Vorvoreanu](https://mihaelav.com/), [Xavier Fernandes](https://www.linkedin.com/in/praphat-xavier-fernandes-86574814/), [Juan Lema](http://juanlema.com), [Adam Fourney](https://www.adamfourney.com/), [Saleema Amershi](https://www.linkedin.com/in/saleema-amershi/)
|
||
|
||
**Research Contributors**: [Matthew K. Hong](https://www.matthewkhong.com/), [Adam Fourney](https://www.adamfourney.com/), [Derek DeBellis](https://www.linkedin.com/in/derekdebellis/), [Saleema Amershi](https://www.linkedin.com/in/saleema-amershi/)
|
||
|
||
**ACM Reference Format**:
|
||
Matthew K. Hong, Adam Fourney, Derek DeBellis, and Saleema Amershi. 2021. Planning for Natural Language Failures with the AI
|
||
Playbook. In CHI Conference on Human Factors in Computing Systems (CHI ’21), May 8–13, 2021, Yokohama, Japan. ACM, New York,
|
||
NY, USA, 16 pages. https://doi.org/10.1145/3411764.3445735
|
||
|
||
# Microsoft Open Source Code of Conduct
|
||
|
||
This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/).
|
||
For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/)
|
||
or contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with any additional questions or comments.
|
||
|
||
# License
|
||
|
||
This project is licensed under the terms of the MIT license. See [LICENSE.txt](LICENSE.txt) for additional details.
|
||
|
||
# Trademarks
|
||
|
||
This project may contain trademarks or logos for projects, products, or services. Authorized use of Microsoft trademarks or logos is subject to and must follow [Microsoft's Trademark & Brand Guidelines](https://www.microsoft.com/en-us/legal/intellectualproperty/trademarks/usage/general). Use of Microsoft trademarks or logos in modified versions of this project must not cause confusion or imply Microsoft sponsorship. Any use of third-party trademarks or logos are subject to those third-party's policies.
|