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?
Making your writing more readable means using shorter sentences, more common vocabulary words, and words with fewer syllables. Without help, lawyers often go the other way. We are known to use overly-complicated sentences that can be written in the passive voice; too many, and overly subordinate, or dangling, clauses; and it’s conceivable we have a tendency to use Daedalian vocabulary.
The WriteClearly AddOn
- A visually attractive presentation of the readability “score”.
- A list of the sentences, with “problem” words highlighted.
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
- The visual presentation matched our goal of putting content in a sidebar, and already fit the Google Apps design aesthetic. It was easy to use existing CSS classes.
- The example connected to an external API, just like we would have to do.
- The concept of “translating” applies very well to what the WriteClearly API does, offering a suggested replacement for text in the document.
Mapping out the project
The draft WriteClearly API contains a stream of HTML text that was formatted for the existing bookmarklet, including a list of synonyms. We did not have time to create buttons to expand/hide the suggestions, nor to actually make use of those suggestions by inserting them in the text as replacements. Therefore, we decided to use CSS to hide the suggestions and to highlight the troublesome words. Gergely helped us figure out that the key elements that we needed to hide were wc-list and wc-list-full. We hid them by simply adding CSS that set those two classes to display:none. The flagged words had a class of wc-hinted. Our process was running the code, debugging the value of the returned JSON to console, copying and pasting into notepad++ for its syntax highlighting/bracket matching, and trial and error.
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
- Improve the look of the add-on through CSS styling. We tried to use logical structures, such as lists and DIVs, to make this future design process straightforward.
- Better defaults. Right now, text needs to be highlighted for evaluation. Clicking the evaluation button with no text highlighted should evaluate the full document.
- Display synonyms. We hide those currently to avoid cluttering the display–buttons should allow hiding or showing synonyms in context.
- Insert replacement text if the user wants it, and navigate through the open Google Docs document as suggestions and scores are displayed.
- Refactor the code, remove unused cruft, and separate out code, css, and HTML that’s currently in sidebar.html into separate files.
- Working on a project that connects and amplifies two existing platforms let us get quick results. Google Apps, in particular, had some very useful sample code that we could borrow to get started with.
- Setting ourselves limited goals gave us the chance to complete something. A completed project is always easier to understand and present. However, we did think carefully about next steps. We tried to plan and code the project up front in a way that our limited work can be extended into a complete project down the road, without starting from scratch.
It’s often true that the last 10% of a project can consume more than 50% of the project time, but this hackathon demonstrated a great, working and already useful prototype. Open Advocate plans to roll out a production version of the add-on in the next few weeks. I hope that you’ll be able to use it! EDIT: the official Urban Insight version of the plugin is now available on the Chrome Web Store!