WriteClearly: Developing a Google Apps Add-on to Promote Plain Language in the Legal Community

I recently was sent by my employer, Greater Boston Legal Services, to a legal technology hackathon at the TIG 2017 conference in San Antonio, Texas. Our team created a tool that helps legal aid lawyers do a better job of writing for the general public. Statistics show that the average reading level in the United States is between 6th and 8th grade. We created an add-on that connects Write Clearly, a plain language tool developed with funding from legal services programs, to Google Docs. Lawyers and advocates can now use Write Clearly from within Google Docs to evaluate their writing. The app also offers suggestions to make the writing readable at the average grade level. The goal is to get advocates to write letters that do a better job of informing our clients. EDIT: the official Urban Insight version of the plugin is now available on the Chrome Web Store!

A “hackathon” is a gathering of people who know the topic (civil legal aid) and people who can program. Some hackathons are contests, but this hackathon was cooperative, with the 30 attendees from all over the country breaking into teams to work on 7 different projects. Projects ranged from improving the sharing of information, to using artificial intelligence to speed up the legal intake process. A lot was crammed into a short time! We worked for about 8 hours straight in our teams. With funding for legal aid threatened and the need growing, legal technology is set to play an increasingly important role in helping legal services bridge the access to justice gap. I wrote this blog post to talk a little about the hackathon and the Write Clearly tool; the process of developing for Google Docs; and where this project might go in the future. I include some technical background and code, but if you’re just interested in how the app works for end-users, feel free to skip to the description of the project and next steps.

For anybody interested in working on add-ons for Google Docs, I can tell you that the process is surprisingly accessible even for someone new to modern web development, and it can be quite rewarding. It was really fun to spend a day and publish a complete project to the Chrome Web Store. As a model for other projects, I think others could benefit from learning how we were able to develop something useful, quickly, by leveraging existing work.

Unfortunately, I can’t share a public link to the project just yet–the Write Clearly team is working on making changes to the code that makes this work in the background–but all of the code for the Google Apps add-on we created is on Github. Keep an eye here over the next few weeks for the link to the app itself to be made public.

What is WriteClearly and What is Plain Language?

Our Team

WriteClearly, the bookmarklet, does a lot: it highlights troublesome sentences, allows navigation within the document, and suggests replacements. We knew that in our hackathon we wanted to produce a completed project, and that meant focusing on the key functionality and setting ourselves limits. We decided on two goals:

1. A visually attractive presentation of the readability “score”.
2. A list of the sentences, with “problem” words highlighted.

We left out some key pieces that could fit in a completed project: inserting replacement text, navigating through the document, and offering synonyms. Focusing on just the core functionality allowed us to make a lot of progress quickly.

Our final result was a Google Docs add-on that is available in the Chrome Web Store. Unfortunately, because the API is unfinished, I can’t share the link to the add-on yet.

Once the app is installed, a new menu item is available in Google Docs.

Next, the author should highlight the text and click the Evaluate button.

The evaluation runs, and the sidebar updates with the evaluation. Below, from an example run, you can see (1) both a numeric Flesch-Kincaid Grade Level score for the highlighted text and an icon that shows whether the score is “good” (at or below grade 8) or not; (2) a summary for each troublesome paragraph, and (3) specific highlighted suggestions about which words should be changed to make the text more readable.

That’s it for now!

Writing and Publishing a Google Apps Add On in 6 Hours

Understanding the sample code

Working on the runEvaluation function was the core of what we needed to do on the frontend code. We also worked on adding clearly named structural elements that would make it easy to do some future design work. We made a quick effort at separating the code, CSS, and content into separate files, but ran into some roadblocks when the official Google Apps documentation on this seemed not to work. That’s an obvious place to begin refactoring for a final, polished project.

We stopped to evaluate our progress here, and decided that the next steps would likely demand more time than we had available. So we devoted the last hour and a half of the hackathon to learning how to publish the add-on to the Google Chrome Web Store, uploading the finished code to Github, and working on the quick presentation that was set for 4:30. Some roadblocks: the Web Store demands some finicky items, including images in very particular sizes. These were a pain to produce, and technical restrictions made it hard to download and install appropriate software to speed this up during the hackathon. However, we worked through with a combination of Windows Paint and Greenshot.

The final code, complete with messy leftovers from the sample project and some debugging code left in, can be found on Github and is presently licensed under GPLv3.

Next Steps for WriteClearly