Hackathon Participants at LSC TIG Conference, January 2017

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?

Plain language means using language that most of your audience can understand. In the United States, the average adult reading grade level is between 6th and 8th grade. Tragically, it’s estimated that 14% of adults effectively can’t read at all. In legal services, our clients may face additional barriers to understanding our advice, such as English as a second language, trauma, disability, or stress. A lot of a lawyer’s job is giving advice, so it’s easy to see why using writing that our clients can understand is important.

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 existing WriteClearly bookmarklet was developed by Urban Insight for Legal Assistance of Western New York, Inc.® and Idaho Legal Aid Services as part of a TIG grant. The original goal was to help legal services programs use plain language on their public-facing websites. It didn’t work within a word processor, which meant a big chunk of the writing we want to make clear–letters to clients–wasn’t easy to evaluate until now.

Our Team

Literally the day before the Hackathon, Gergely Lekli of Open Advocate finished the key part of the project: an API that we could connect to from Google Apps. Gergely is based in LA and remained available on the Hackathon’s Slack channel to answer questions about both the API and the front-end code we needed to connect it to Google Apps.
On-site at the hackathon, our team was just two. Anna Steele of LAWNY had helped work on the original WriteClearly bookmarklet with Abhijeet Chavan of Urban Insight, and during the hackathon she worked on the overall direction of our plan, the design and content, and a lot of the HTML code. The idea for the Google Apps add-on was conceived last year by Abhijeet, Anna and Gergely. I (Quinten Steenhuis) am a lawyer and systems administrator at Greater Boston Legal Services, and I worked on the programming.

The WriteClearly AddOn

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.

The WriteClearly add-on in the Chrome Web Store

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

Menu: Add-ons | WriteClearly | Start

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

WriteClearly Sidebar, display 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.

Output from the WriteClearly add-on, displaying (1) score (2) summary of each paragraph (3) suggested improvements.

That’s it for now!

Writing and Publishing a Google Apps Add On in 6 Hours

If you’re interested in the technical process of writing the add on, keep reading. Otherwise, you may want to skip ahead to the next section where I’ll talk a little more about next steps for the project.
Creating the Add On drew on specific knowledge that was pretty new to me: specifically, the syntax for JavaScript callbacks and JSON. General programming principles are not too different from platform to platform, and I had tried some projects that used both. Still, working through slightly unfamiliar syntax meant a good chunk of time was needed for referring to documentation and examples instead of working on program logic. Jon, who was assigned to the Houston AI project being developed by Legal Server, helped out by looking over the example code and explaining some of the unfamiliar syntax. The sharing of knowledge was one of the great aspects of this collaborative hackathon.

Understanding the sample code

The first task was to find some documentation and figure out what existing work could be reused to speed up our project. Google’s sample translation Add On for Google Docs fit the bill perfectly.
On the airplane, I tried to get a little prepared for the hackathon by reviewing some of the Google Add On developer’s documentation. Google has a “Quickstart” series aimed at getting you started at writing code for Google Apps in just five minutes. For an experienced frontend developer, five minutes might be literal, but even for myself it was a great start. Key features that made this a perfect sample project:
  1. 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.
  2. The example connected to an external API, just like we would have to do.
  3. 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

I determined that only a few new functions would need to be written for our project: the backend code in “code.gs” and the frontend code in “sidebar.html”. The new backend function, getTextEvaluation, is about 30 lines of code, and is modeled on the getTextTranslation function from the sample project. There’s a bunch of syntactic sugar to get the query and the results in the proper format, but the guts of the function is a call to UrlFetchApp, Google App’s function that connects to an external API.
UrlFetchApp has two arguments: a URL, and an “options” object that includes the payload for the API and a method (POST or GET). The WriteClearly API expected a JSON payload with just two parameters: JSON=1; and CONTENT, the text to analyze in HTML format.
Two tools were really helpful in testing out the WriteClearly API and learning how to use it in the Google Apps code: HurlIt, which lets you test a POST query against a URL, and JSON Editor Online.
The other key function needed to be written in sidebar.html, runEvaluation. The main logic is in the unnamed callback function after line 10, “.withSuccessHandler” The code replaces the contents of two named DIVs in the HTML, #fkgl-index, and #suggestions. For #fkgl-index, we use some simple logic to check the returned grade level, and assign a smiley face for a “good” reading level, and a frowny or angry face for a “bad” level. We also display the numeric value. The content of the suggestions DIV is replaced with an unordered list that contains a summary for each flagged paragraphs.

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

We ran out of time to implement our full vision for the project. Here are a few future improvements that stick out:
  1. 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.
  2. Better defaults. Right now, text needs to be highlighted for evaluation. Clicking the evaluation button with no text highlighted should evaluate the full document.
  3. Display synonyms. We hide those currently to avoid cluttering the display–buttons should allow hiding or showing synonyms in context.
  4. Insert replacement text if the user wants it, and navigate through the open Google Docs document as suggestions and scores are displayed.
  5. Refactor the code, remove unused cruft, and separate out code, css, and HTML that’s currently in sidebar.html into separate files.

Conclusion

This was a very rewarding project. We learned a lot about developing and publishing a Google Docs add-on, and we managed to produce a usable prototype. I left with some key lessons:

  1. 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.
  2. 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!


0 Comments

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.