Becca Saines is a Software Engineer for Streak. Prior to graduating Hackbright in Fall 2016, she was a middle school math and science teacher for Teach for America. In her role at Streak, Becca was tasked with building out the company’s Zapier integration. Here, she shares her wisdom, documentation, and advice on the process.
Documentation is mission critical to the success of a new developer product, but finding the sweet spot for maximizing audience engagement is no trivial task. Lucky for you, my loss (of time) is your gain. I hope this blog post will save you a ton of time, effort, and that you’ll be building on this reliably awesome tool faster than you can say Zapier.
Vocabulary
First off, the Zapier docs do not have a dedicated glossary of keywords and terms. You can get the gist from their individual category sections, but having a dedicated reference list certainly would have softened the slope of my own learning curve.
Another benefit of a dedicated glossary is being able to compare the keyword definitions for developers and non-technical end-users side by side. The Zapier documentation does do this to an extent (hats off, Zapier!) but still assumes a level of knowledge above what I had as a developer just beginning to work on Zapier.
Draw me a picture
In general, I feel there is a lack of pictures in technical documentation. I understand the reason for this — pictures are not easily updated, and even more so than text, should be geared towards a specific audience. However, I find them obscenely useful for getting a big picture context when I’m starting to learn something, so here is my (crude) picture of how Zapier works, specifically geared towards beginners: 
Super Important “Gotchas” that will save you oodles of time
- If you use console.log() with anything too large, any logs prior will not show — only the logs after will appear.
- You can return an empty array to stop a Zap (instead of throwing an error, which might potentially pause the Zap for the user if the error is thrown too many times).
- Datetime: Zapier’s standard datetime format is an ISO-8601 formatted string. This means that if you receive a date from Zapier for a user’s action and your API expects a UNIX timestamp, you’ll need to use moment.js (thankfully a library Zapier Scripting allows access to) or `new Date()` to convert it via scripting before passing it to your API.
- You can access information in the user’s Zapier profile via scripting! For instance, `bundle.zap.user.timezone`will give you the timezone the user entered on their Zapier profile.
- Pre’s and Posts in Scripting: There are a lot of suffixes you can put on a key (that’s the thing from the trigger or the action that identifies which action/trigger you’re scripting about) — pre_poll, pre_read_resource, post_search, pre_write, etc. The myriad of options were really overwhelming for me when I first started developing features on our Zapier app. I wish someone has summed it up like this: pre_stuff is for before Zapier makes the request to your API. As a result, it’s mainly going to be used for things like adjusting the request url, or the headers of the request. The post_stuff is used after the request for data has been made, and so is mainly for adjusting the data you receive in the response to the request.
Streak’s integration with Zapier has enabled our users of varying technical capacity to really make the most out of our API. It’s been a fantastic tool to engage and create efficiency for our users through automation, and it’s all taken care of in a user-facing UI that’s friendlier than a border collie. A further plus is that Zapier’s support — both for developers and users — is top notch. I’ve been impressed with both the speed and quality of the support they consistently offer. As with any new technology tool, the learning tool can be steep. But the good news with Zapier is that you’re not going it alone.
This article was originally posted by Becca Saines on Medium. It has been abridged for Hackbright Academy. Find the full article, and more of Becca’s writing on Medium.
Interested in learning more or hiring a bootcamp grad? Join the ranks of other top tech companies and become a Hackbright Hiring Partner.