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.

When there is just one YAML file in the package, use a descriptive name for it

Most interviews use just one YAML file. This name can "leak" into the user's view in some cases, so it is usually best to make it a complete, descriptive filename.

For example: eviction.yml is probably a better filename than interview.yml. It will be easier to know what file you are working on, and the name will be more descriptive if it shows to the final user of your tool.

The descriptive name can, and often will, match the name of the package.

Your interview YAML name should avoid:

• Suffixes like _final, _draft, etc., even when you are in the middle of building it. Use GitHub version control instead to track multiple versions of the work in progress.
• Any other "insider" information that you do not want the public to see, like the statute number.

Make sure to remove characters that accidentally got added during the edit process, like (1) that might have been added when you download the file to a Downloads folder that already has a copy of the same file.

When you have multiple files in a single package, give each file a clear prefix

While simple interviews have one YAML file, there are three strong reasons to have more than one YAML file in a single Docassemble package:

1. If one package has multiple, distinct interviews contained within it, perhaps for different audiences, like children, parents, or interested people, or someone filing a complaint or someone answering it.
2. If one interview assembles multiple complex forms. In that case, it may be helpful to put any unique questions for each form, as well as the attachment block, into its own YAML file.
3. If the YAML file simply is getting too large to easily manage. In that case, you might break up the YAML into multiple files that are easier to edit. In this case, make sure the reasoning for each file is clear. E.g., you could separate the interview's metadata, questions, and logic into three separate files.

Even if an interview makes sense on its own, you may want to make it re-usable as a module in other interviews. For example: a fee waiver, an interpreter notice, or a request for accommodation. In that case, you want to make sure that the mandatory logic and metadata are separated from the part you want to re-use in other interviews.

Keep things simple when you can! Think ahead to the developer experience. If you are dividing work across multiple authors, think through what a single change will look like. Can an author make a change without having to edit multiple YAML files in most cases?

Our current recommendations to name the files in this scenario are:

1. Any runnable files in your package should be named main.yml. If there are multiple runnable files, give each file the prefix main_. (main has a long history in computer programming.)
2. If the interview assembles multiple documents, you can make a separate YAML file for each document that contains the unique questions it needs and the document's attachment block. Name it after the document itself, e.g., financial_statement.yml. (be consistent with this: if the separate documents are very short, you may not need this, but it should be all or nothing inside a single package.)
3. Name the file that is used by multiple related interview endpoints shared.yml.

info

Remember, there should be only one mandatory block in a given combination of YAML files. That means you should never put a mandatory block in the files for each individual document.

To group logic that you might want to run with the template it relates to, without making it mandatory:

1. use the named block pattern for the interview order block
2. reference your named block in a mandatory block inside the main file that users will run.

While in the development phase, you might want to temporarily test a single document at a time. You can do so by making, e.g., a financial_statement.yml and a main_financial_statement.yml file. The mandatory block will be in the main_financial_statement.yml and reference the named block inside the financial_statement.yml file. Be careful to not rely on this for more than quick tests! You'll always want a final round of testing when financial_statement.yml runs in combination with the forms you want the user to interact with.

If you need to subdivide very long YAML files further:

1. Label files that contain only questions questions.yml, or prefix with questions_. If the name is too long, ql_eviction.yml is a reasonable abbreviation that follows the Assembly Line's existing conventions.
2. Name shared files that contain other kind of functionality, e.g., integration with a separate service, support.yml or prefix the filename with support_. E.g., support_legal_server.yml, support_s3.yml.
3. Name files that contain only logic logic.yml, or prefix with logic_. E.g., logic_eviction_defenses.yml.
4. Name files that contain functionality that only affects the appearance of the interview (e.g., loading CSS)theme.yml or visual.yml.

Examples:

An interview with exactly one YAML file in it

Filename	Purpose
eviction.yml or main_eviction.yml	The one YAML file containing mandatory blocks, attachments, metadata. The whole enchilada.

main_eviction.yml is slightly more flexible for future growth. But, for many simple interviews, you know you do not need this future flexibility.

A fee waiver that can be assembled by many different interviews

Filename	Purpose
main.yml or main_fee_waiver.yml	The runnable interview file when someone wants ONLY the fee waiver. Contains mandatory code and metadata (e.g., interview title), and the document bundle (al_user_bundle and al_court_bundle).
fee_waiver.yml	Has no mandatory logic. Contains questions and the attachment block, and a "named block" with interview order logic that can be referenced in a parent interview's mandatory interview order block.

An interview that assembles multiple documents in different combinations depending on audience

Filename	Purpose
main_petition_for_guardianship.yml	Entry point for an interested person. Has metadata, a mandatory interview order block and the document bundle (al_user_bundle and al_court_bundle).
main_object_to_guardianship.yml	Entry point for the person whose right is being restricted (e.g., a parent or incapacitated adult). Has metadata, a mandatory interview order block and the document bundle (al_user_bundle and al_court_bundle).
shared.yml	Contains shared questions, and only questions (perhaps with some basic code setting simple shared variables), for the guardianship process that multiple documents might need written the same way.
petition_for_guardianship.yml	Contains unique questions for the petition and attachment code. No mandatory blocks.
bond.yml	Contains unique questions, logic, and attachment code for a bond form.
request_for_counsel.yml	Contains unique questions, logic, and attachment code for a counsel request form. No mandatory blocks.

A complex interview with only one entry point but where managing a single YAML file is too cumbersome

Filename	Purpose
main.yml or eviction.yml	Metadata, mandatory logic, document bundle
questions.yml	Only questions
logic.yml	Code blocks that define various behavior, such as whether a defense or claim will be made.
support_legal_server.yml	Support / setup code that handles connecting to the Legal Server CMS.
support_office_365.yml	Support / setup code for connecting to Office 365.
theme.yml	Code / setup / metadata that controls the appearance of the interview, but nothing else.

info

Above we suggest that you can use either main.yml (a functional name) or eviction.yml (descriptive).

Remember that the descriptive name is great when you are sure that you will only have one "descriptive" name in the package. If you might edit the package later to add multiple documents, it might be best to start with main.yml right at the start of the interview.