I had the pleasure of spending Friday at Docacon presenting to and learning from 30 Docassemble users from around the country—and I learned so much from all of them. It was exciting to see so many people building amazing projects.

In October 2017 I made a comparison of the options for building Turbotax-like guided interviews for legal aid organizations, and announced that my choice was Docassemble. 10 months later my tenant-facing project for Greater Boston Legal Services is in a “soft-launch” phase. I am very proud of the work that we’ve done, and I have learned a lot on the way.

Was Docassemble the right choice?

Emphatically, yes. I’m very happy with the choice to begin learning Docassemble and building my project with it. Over the last 10 months Docassemble has improved by leaps and bounds and I forsee a great future for it as long as Jonathan Pyle can keep up his tireless pace developing it in his “spare time” (a full-time job for a mere mortal).

What sets Docassemble apart?

Attractive by default with end-user friendly features

Of the choices available to us, Docassemble has the nicest default appearance and is very easy for an end-user to navigate. This is honestly the most important point. Building a complex interview on any platform is a lot of work. The work is worthwhile on Docassemble because you can create the best looking interview possible, one that is usable on desktops, smart phones, and even via interactive SMS messaging.

It’s simple to include user-friendly features like pop-up help, images, and videos. Docassemble also integrates with text messaging and email, allowing you to send completed documents by email or send reminder text messages about court dates, for example. Of those examples, we used all of them except for text messaging, but I was inspired by the talks at Docacon to integrate court date reminders in a future release.

Unlimited Customizability

Docassemble is free and open source software, released under the MIT license. Free is nice, but keep in mind you will need to pay for hosting (I use Digital Ocean for $10 a month and Azure blobs for a few additional pennies. If you want a complete hosted solution without having to learn and manage Docker, DNS, and security updates, Community.Lawyer‘s $25/month offering is an amazing deal). There’s no required license fee for either developing in Docassemble or for your users.

More than the low price, what I like about Docassemble is its open source nature, which means you can easily extend and build in new functionality—if you want to.

There’s no real ceiling for your project if you build it on Docassemble. If you color inside the lines (thanks Jonathan for that metaphor) Docassemble is straightforward to use. But you’re also free to pull in information from a customer’s credit report, like Upsolve is doing for bankruptcy clients, generate maps with Google’s API, customize the display with custom CSS and Javascript code, and so much more.

We kept the customization simple and we pull in data from outside sources (like maps, lists of courts, and lists of discovery requests) but the only visual customization we made is to use an out of the box Bootstrap theme.

A complete programming language under the hood

In an effort to make it easy to learn, most languages for building guided interviews are limited and inflexible. Docassemble is built on Python and exposes the full Python language for you to use for the logic in your interview. There is a tradeoff here—Docassemble is more complex because of it—but Python is a very user-friendly programming language. If you stick to the features that HotDocs offers, for example, the syntax will look very familiar.

Screenshot of example code

To any HotDocs developer, even the more complicated logic here will look pretty friendly.

In our guided interview for pro se tenants, it was very helpful to have the full strength of Python at hand. Python is object oriented. In HotDocs, keeping track of a list of variables that are used in more than one place is fine for short interviews, but in a longer interview, it’s easy to get lost with copy and pasting, especially when making later updates. REPEATs offer only a limited solution. In Docassemble, using object-oriented techniques, you can keep track of related variables easily in one place.

For our eviction interview I built custom objects to store discovery requests, Massachusetts court names, functions to connect to Google Sheets, and made use of the full expressive power of Python to keep the logic short and concise.

Example of Object-oriented programming from template

Creating the custom method “any_in_category” leaves the logic needed to decide whether to display the “Landlord’s Claims” section in the template neat and readable.

Room for growth

Docassemble has room to improve with error handling, question editing, and the interview building workflow.

Halting problem aside, it would be nice if Docassemble warned you earlier on about potential errors in the logic. For a longer interview like ours (180 questions in the paper form, many more variables in Docassemble), it is a bit tedious to go through 10 screens to test the new one you added, and then get an error before you get to page 15. One thought is to include a linter. Or, to approach it from the other angle, an automated testing technique like a fuzzer that enters random (but datatype appropriate) data to see if your interview will run through to the end.

Docassemble offers a way to edit your answers, but it is a little clumsy for now and takes a lot of work by the interview author. Users want to be able to edit and change their responses, and for some workflows (like our group clinics) an attorney may want to allow the user to do most of the work but make corrections at the end. Storing answers and reusing them in different interviews can also be improved. It sounds like Jonathan is already working on improvements to this area.

A natural way for a lawyer to build a guided interview is to start with the template file (the document to automate). After all, the template file is usually complete before the project even starts, and is based on existing work produced by the attorney. After thinking through variable names, it’s natural to mark up the template, and only then, to think through and test the interview questions. In Docassemble, if you have a variable listed in your template that doesn’t have an inteview question connected to it yet, the interview will stop with an error. It would be nice to allow the interview author to test out the interview questions even when the questions don’t yet cover the full template.

For testing more complete interviews, we experimented with using gherkin scripts, but they aren’t designed for this exact need and aren’t good for testing an interview that is undergoing heavy changes.

These aren’t things that I know to be handled better in other guided interview platforms, but they seem solvable in an open source platform like Docasemble. Knowing Jonathan’s indefatigable pace, I wouldn’t be surprised if they were fixed before I have a chance to write an update a year from now.


There are still reasons that I would build a project in HotDocs. HotDocs is non-linear, mature, and works well for form libraries. But for any user-facing project, Docassemble offers serious advantages over the other solutions I have tried on the market. I’m very happy with our choice and I can’t wait to build more projects on Docassemble.

Not sure where to start? I wrote a blog about how to get started with Docassemble. My friend Jason Morris and I also offer Docassemble consulting services as Lemma Legal. We can help you with installation, training, and creating your first interviews.


Jason Morris · June 27, 2018 at 8:16 am

If you have the playground open in one tab and a test run of the interview in another, you can navigate to screen X, find a problem, open the playground tab, edit the code, save it, go back to your test run tab, refresh, and the changes will appear! No need to start the interview from scratch. Great review!

    James · September 29, 2020 at 1:41 pm

    @Jason Morris — I have nearly lost my vision the last 72 hours – You trick has saved me a barge load of aggravation and time.

    Any suggestions for getting images and/or signatures onto .PDF template? I can get it to work with docx but not PDF. The PDF has a better fixed format that I will eventually need.

Leave a Reply

Avatar placeholder

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.