Skip to main content

Interview files

Docassemble interviews are written in YAML.

They may also contain:

  • template files (e.g., DOCX, PDF, or Markdown (.md) files)
  • images
  • css
  • javascript
  • data sources in CSV, XLSX, or JSON format

Keeping your files neat and organized can help other developers understand your code.

Use Python conventions for variable names and Python code in your YAML files​

See Python style guide.

Organize and name your files​

Use descriptive package names; include state and forum identifiers​

For the Docassemble package, use names that help someone understand at a glance what your form does and where it can be used:

  • include the form function and subject area. E.g., EvictionStay not just Stay or Motion
  • include the state abbreviation if it is state-specific. E.g., MAEvictionStay
  • include a forum abbreviation if a form with a similar name exists in a more common forum. E.g., MAAppealsEvictionStay if you can request a stay in the Appeals and the trial courts. But: you likely don't need to specify MATrialEvictionStay if most of your forms are designed for the trial level.
  • unless you have a good reason, avoid internal court form reference numbers in package names (you may want one interview to handle multiple forms in the future)

Descriptive names will help you and external parties looking for examples in the future locate your package on GitHub.

Avoid spaces in file names; use lowercase letters​

Files in your Docassemble package, including YAML files, Python modules, and any static resource files or data sources, should all be be named without spaces. You may choose to use snake_case (underscores separating words) or kebab-case (hyphens separating words). Using snake case avoids problems with some command-line tools, as well as being more consistent with Python file name conventions, but one challenge is that snake_case underscores can be hard to see in a file browser window.

Use lowercase letters in file names. Some file systems (Unix and Linux) are case sensitive. Using a consistent case can reduce problems. Lower case is the most commonly used convention.

Avoid using leading numbers in file names​

Where possible, avoid using leading digits in file names. Leading digits are not valid in Python variable names, and it is often convenient to have variable names and file names have matching prefixes.

Use descriptive names for YAML files​

When you are editing a file, the context sometimes is missing in places that the file name is displayed. Therefore, you should prefer using file names like "eviction_interview.yml" to just "interview.yml". Have the name describe the function of the file, and give it a name that might be meaningful and build trust with your end user.

Avoid using numbers, underscores, and other markers to indicate that you have a "final", "draft", etc. interview even during the editing process, as these have a chance of getting leaked to the public. Instead, use version control to track the history of your files as your project develops.

Use a small number of YAML files for each project​

It can be a frustrating game of "which file is that in, again?" if you have too many YAML files. Start out with just one YAML file for your interview. Start adding additional files when:

  1. you want to use an interview like a module inside another interview
  2. your YAML file is thousands of lines long and you have clear functional separation between each file. For example: code, style, questions; or maybe "eviction", "appeals", "bad_housing_conditions".
  3. you need to split work between multiple developers and you are running into challenges with overwriting each others' work
  4. you need non-technical members of your team to be able to make changes with confidence. You might choose to separate code from question language, in that case.

Use clear filenames for modular interview files​

Docassemble allows you to include one interview into another interview file. If you want to design a file to be re-used:

  1. avoid putting any mandatory blocks in the file
  2. use the named block pattern for the interview order block
  3. reference your named block in the file users will run
  4. describe the function of each file in the name

We recommend the annotations:

  1. to_include for the file with the interview logic, attachment block, and questions
  2. standalone for a file that includes and then runs just one to_include file
  3. umbrella for a file that generates multiple templates

Example:

FilenamePurpose
eviction_to_include.ymlThe interview order block, questions, and content for one interview that cannot be run from this file.
eviction_standalone.ymlInclude and run just one interview about evictions
eviction_umbrella.ymlInclude and run multiple interviews related to eviction