AI summary: Docassemble helps you build guided web interviews that ask questions, use the answers in logic, and generate documents or other outcomes. For a first project, access a test server, create a small YAML interview in the Playground, run it with several answer combinations, and add a simple DOCX template. Review the wording and output with real users before packaging and deploying the interview.
A static intake form can leave staff chasing missing answers. Docassemble asks relevant questions one screen at a time and uses the responses to create a result.
This Docassemble tutorial builds a small client intake interview and summary without complex legal rules.
What Is Docassemble?
Docassemble builds mobile-friendly interviews that can end with advice, an application, or a document. Legal aid teams use it for guided forms and firms for intake; it also supports other workflows.
Four terms make the rest of this guide easier:
The interview is the user-facing product. The YAML and template are how you build it.
What You Need Before You Install Docassemble
You need a server, a developer account, and a small process to automate. The official guide recommends Docker for local learning. On an organization server, request a test environment.
Choose one outcome: a one-page intake summary. List required and optional information.
Step 1: Install Docassemble or Open Your Test Server
Start Locally with Docker
Docker runs the Docassemble software in a container. Follow the official Docker installation instructions for the current setup rather than copying a command from an old article. The immediate goal is straightforward: open the Docassemble site in your browser and sign in to a test instance.
Production needs hosting, backups, access, and support. The deployment guide covers Docker, Docker Compose, and Helm.
Use an Existing Organization Server
On an existing server, confirm the test URL, developer access, and who can see responses. Use fictional client data.
Step 2: Get Comfortable with the Docassemble Playground
The Docassemble Playground lets you edit an interview YAML file and run it immediately. After signing in, open Playground, create a project, add an interview file, save it, and select the option to run it. Return to the file after each test and change one thing at a time.
The Playground is a workshop; production calls for packaging and version control. See the official Playground guide.
Step 3: Build Your First Docassemble Interview
Ask for a Name and Show the Result
Create a YAML interview file with this small example, adapted from the structure in the official interview documentation:
question: What is your name?
fields:
- Name: client_name
mandatory: True
question: Your intake summary
subquestion: |
We have recorded your name as ${ client_name }.
buttons:
- Exit: exit
The first block asks a question and stores the answer in client_name. The — line separates blocks. The second block is mandatory and refers to that variable, so Docassemble asks for the name before displaying the summary. The exit button ends this basic exercise. Theinterview authoring guide covers this question-and-variable pattern.
Test short and long names. If it fails, check YAML indentation.
Add a Contact Question
Next, ask whether the person wants to provide an email address. Show an email field only when the answer is yes. This introduces conditional logic without turning the intake into a large rules engine. Test both paths and make sure the final summary does not display an empty “Email:” label for someone who skipped it.
A useful interview asks only what is needed to reach the outcome. A subject-matter expert should approve any eligibility or legal decision rules before they are introduced.
Step 4: Generate a Document from the Answers
Begin with a one-page Word template containing a heading, the client’s name, and contact preference. In the template, a variable can be inserted using the DOCX template syntax, such as {{ client_name }}. Upload the file to the Playground’s Templates folder, then reference it in an interview attachment block.
Docassemble supports Docassemble PDF generation from a DOCX template and can also fill fields in an existing PDF. A DOCX template is often an approachable first exercise because you can edit the layout in Word. Follow theofficial document assembly guide for the exact attachment syntax and supported formats.
Download both output formats you intend to offer. Check long names, missing optional answers, page breaks, and whether the finished document says what a staff member expects. A file that downloads successfully has not necessarily passed content review.
Step 5: Make the Interview Easier for Real People
Write each question in language your intended user understands. Explain why you need sensitive information and avoid asking for details that will not affect the result. Use helpful validation: “Enter an email address such as name@example.com” is more useful than “Invalid input.”
Try the interview on a phone. Can someone understand the question without seeing previous screens? Can they correct a mistake before submitting? For US legal aid or court-facing tools, test with people who reflect the actual audience and have the legal wording reviewed separately. Explore moreDocassemble use cases and theindustries served when planning a larger application.
Step 6: Test More Than the Happy Path
Run at least four scenarios: a typical client, someone who skips optional fields, someone with an unusually long or unexpected answer, and someone using a phone. Check the question sequence and generated document in each case.
Ask different reviewers to focus on different risks. A legal or program expert checks the rules and wording. A developer checks the logic and errors. A representative user checks clarity. The organization decides how responses will be stored, accessed, retained, and deleted before real clients use the interview.
Step 7: Move from Playground to a Maintained Application
A Docassemble package can group interview YAML, templates, static files, and optional Python modules. Packaging makes it easier to track changes and deploy a known version. Keep development, review, and production separate; decide who can publish an update and who responds when an interview breaks.
Thepackage documentation explains the file structure. For advanced design, reviewDocassemble solutions anddevelopment services.
Beginner guides often end when the PDF appears. A real guided form continues to change: a rule is updated, staff spot confusing wording, or a template breaks after an edit. Assign an owner for content, a reviewer for legal changes, and someone responsible for testing and deployment. Keep a small set of example interviews that must still work after every update.
This is especially important when a user treats the document as ready to file. The organization needs to make the limits of the tool clear and ensure the final content receives appropriate expert review.
How Do You Get Started with Docassemble?
To get started with Docassemble, run or access a test server, open the Playground, create a short YAML interview, and test every answer path. Add a DOCX template if you need a document, then review the questions and output with users and subject-matter experts. Package and deploy the interview only after you have a plan for updates, data handling, and support. Start with the official Playground, interview, and document guides.
Where DocassembleDevelopment Can Help
DocassembleDevelopment can help turn an existing form into a guided interview, develop YAML and templates, test difficult paths, and prepare a maintained deployment. If you have a form and a clear intended outcome but need implementation help, you can hire a Docassemble developer. Share the current form, the questions users struggle with, and the document or decision you need at the end.
Frequently Asked Questions
Do I need Python to start using Docassemble?
No. You can begin with a simple YAML interview. Python becomes useful when the workflow needs more advanced rules or integrations.
Is Docassemble only for legal documents?
No. Its guided interviews can support many processes, including intake, applications, and other document workflows. Legal services are a common use case.
Can Docassemble produce Word and PDF files?
Yes. It can use DOCX templates and produce document outputs, including PDF. It can also fill PDF form fields. Choose the approach that fits your source document and test the rendered result.
What is the Playground for?
It is the development area where you create, edit, run, and refine interview files and templates before packaging the application.
Can I publish my first Playground interview immediately?
Test it first with different answers and devices, review its content, decide how data will be handled, and assign an owner for future updates. A working demo is the beginning of a usable service.
English