Reilly Wood

I’m a member of a nonprofit called Abundant Housing Vancouver, and as you can probably tell, I happen to do some programming too. In 2017 I was able to spend a lot of time combining these interests which was pretty great!

Over a few blog posts I’ll briefly outline the projects I worked on – they’re all open source and who knows, they might even be useful for other housing advocacy groups someday. First up: the Abundant Housing Vancouver Letter Builder.

Background

In Vancouver, many housing projects are decided on at contentious public hearings. At AHV we often try to rally support for good projects at the public hearing stage, but it’s hard because feedback at hearings tends to be biased against new housing for structural reasons. Without going into too much theory, we need to make it easy for people to support new projects, or nobody will. Thankfully Vancouver accepts hearing comments via email – it’s much easier to send an email than it is to spend an entire evening waiting at City Hall to speak!

Still, it takes a long time to write an email if you’re starting from scratch: first you need to familiarize yourself with the project and the public hearing process, then take quite a bit of time to actually write it. We needed a way to quickly 1) describe a project to supporters, 2) help them compose a personalized email to the City. Inspired by a clever letter generator project by Melody Ma and Ivy Tsai, we decided to write our own tool for this.

Design Goals

1. The tool should be really quick to use
2. The letters generated by the tool should not look like form letters! They should vary from one another and be easily customized by users
3. It should be super easy to configure the tool for new projects

Finished Product

Here’s what we ended up with. You can give it a spin, the testenv=true parameter ensures that it won’t really send emails. It’s quite easy to use:

1. Fill in personal information (name, address)
2. Pick the following from a list of options: your relation to the project, what you like about the project, and what you think could be improved
3. Click Generate Letter and a letter is generated based on your input, using randomized text.
4. Edit the letter if desired then click Send Letter

After that, the letter is sent to a Slack channel where we can approve it:

If the letter isn’t spam, we click Approve and it gets sent to the City of Vancouver. Done!

Technical Details

I wrote the letter generator front-end in TypeScript, using Angular 4 with Bootstrap theming. I used angular-cli for setup and scaffolding.

All configuration for the front-end (project info, text snippets for letter generation) lives in a Google spreadsheet and I read it in using the excellent Tabletop.js. Configuring the letter generator for a new project is as easy as adding a new row to the spreadsheet. Project descriptions are written in Markdown and then converted to HTML using the handy ng2-markdown-to-html library.

The front-end code is available on GitHub and if it sounds useful I encourage you to fork it and give it a spin.

The front end passes messages off to an Amazon Lambda function which was written by the remarkable Roman Lisagor. This function handles notification+approval (via a Slack webhook) and then sends the email using AWS SES.

Lessons Learned

This was largely an educational project for me – it had been years since I paid much attention to web development and I was keen to try building something in Angular. As such, caveat emptor if you end up using the code.

Programming in TypeScript is pretty nice, especially compared to the JavaScript of yore. Compile-time safety has saved me many times, and declaring variables with let eliminates the usual JavaScript scoping confusion. Newer versions of JavaScript also support let but… personally I’ll stick with TS for the static typing alone.

I generally liked Angular, but good lord does it ever generate huge script files. A simple project like this compiles to 1.3MB of scripts (in the production build, mostly vendor scripts). I cringe to think about how much bandwidth is being used to for relatively little program logic.

angular-cli is very helpful for getting all the necessary scaffolding set up, and I wouldn’t hesitate to use it again.

Tabletop.js was a lifesaver. For small+casual projects like this, sticking our config in a Google spreadsheet has a lot of advantages:

• Google handles permissioning and authentication pretty well! It’s trivial to control access to the ‘database’ and everyone already has a Google account
• The configuration is easily read and edited by non-technical people
• You don’t have to spend time administering and hosting a database somewhere

I would shy away from this approach for most professional projects, but if you just want to hack something small together you get a lot for free with Google Sheets + Tabletop.js.