Best practices for developing interviews

Interview files

Use one file until it becomes necessary to separate into multiple interview files.

Reasons to separate:

• Multiple authors working at same time
• Question set will be re-used in a different interview

Controlling question order

Use a mandatory code block at the top of the interview which lists the variables in the order that you want them to be gathered. No other questions should be made mandatory. Avoid using the need statement if at all possible (sometimes it seems its necessary to trigger seeking variables for sending an email).

ID tags

Each question in the interview file should have an id tag. Use id tags for mandatory code blocks as well. id can include spaces, should be descriptive. It will be used for tracking in Google Analytics as well as debugging.

Writing questions

Start with an intro screen

A "welcome" splash screen is a good best practice while developing an interview (it will help with performance of the playground variable list). It's also a useful orientation for most interviews, except very short ones aimed at advocates who don't need orientation to the tool.

Use subquestion for longer text, question for headings/titles

Your users are likely to skip through content to find the key information they need. Use question/subquestion specifiers consistently to guide users to important information. Typically the question field will be a heading, and the subquestion will have explanatory text. Keep this text as short as is clear and readable.

Use one question per field

Forms often have compound questions (e.g., "Are you over 50 or a veteran?"). There's no excuse to do this in Docassemble. You can easily use a small code block to combine multiple questions into one. It's much easier for users to answer one question at a time.

Use the right field type to help the user

• If you have a small number of valid responses, use radio buttons. They are easier to use on a smartphone.
• If you have a small set of likely responses, either use a combobox or use radio buttons with "other". Not all users will understand comboboxes, so pay attention in user testing.

Use visuals to enhance, not distract