The Art of the Tech Review

A year and change ago, I joined Osio Labs as a marketing coordinator, jumping headfirst into a new role, new company, and a new distributed work lifestyle. But newest of all was learning the value of what we sell: technology knowledge. How do you communicate that? And how do you differentiate yourself in a crowded market?

Because understanding that is central to my job, I needed to learn what happens to tutorials during technical review and Jon Peck, technical reviewer for Hey Node, kindly obliged. It turns out, an online tutorial is a small chunk of ice, and the process to make one is an iceberg built of Trello cards. What follows is an excerpt from our interview.

An interview with Jon Peck

Philippa: How did you get involved with the Osio Labs crew?

Jon: I’ve been active in the Drupal community since 2011 and I’ve become friends with some Lullabot peeps who I met through camps and conferences. Around the same time, I started creating educational content for Lynda.com about software engineering with a focus on PHP and Drupal. After working for Pantheon Systems, I moved to Four Kitchens, an agency with a remote culture like Lullabot. I’ve since moved on from Drupal to Node.js, but I’m still friends with many in the Drupal community. When I heard about Hey Node, I reached out to Addi and offered to help with technical content.

P: Where are you based and what’s your wheelhouse?

J: I’m in the San Francisco Bay Area of California. I’m primarily a back-end engineer, but with a balance of full stack and front-end experience. I prefer working on large scale projects with a heavy emphasis on performance and optimization. Big and complex is fun!

P: You review Node.js tutorials for us. Why did you choose to learn Node.js?

J: Four Kitchens worked in both Drupal and Node, and I was lucky to have a supportive learning environment with work in both languages. I made it known I was interested in learning in my off time doing professional development. I figured when I was ready to contribute in Node, I’d raise my hand.

I chose to learn Node.js for a number of reasons. First, it’s a high-performance language with a lot of flexibility. I was really impressed with the enthusiasm of the community; I had felt some of the same energy in Drupal, and it was refreshing. The open-source modules were varied and the contribution system was inclusive and empowering. The language itself was also rapidly progressing alongside ECMAScript. Finally, I liked the accessibility, which was similar in some ways to PHP. People can learn the basics easily, but with practice it can be incredibly powerful!

P: How did you learn it?

J: By having a tangible goal. Four Kitchens was doing API work for a large media publishing client, so I focused on what I needed to learn in order to make a RESTful API. Once I had something, I asked mentors to tear it apart and tell me what I did wrong to make it better. It took using it, making mistakes, correcting those mistakes, and a cycle of peer review to level up and adopt the code style of my team -- to really understand how and why they were doing it.

P: What exactly is a technical review and what does it entail?

J: Abstractly speaking, a peer review should be about whether the code fulfills the intent of what was requested. When I receive a script, I start by doing the same exercise as when I review my own script: I ask what the intent is. What am I supposed to learn? If I’m unfamiliar with the subject, I research the concept and review everything. If there’s an insertion like the best way to do XYZ, I’ll check that for accuracy. If there’s a code sample, I run it in a code editor. I then analyze whether that code sample actually demonstrates -- and effectively demonstrates -- the concept being discussed.

With educational content, the next step is to literally read it aloud. It might seem out of scope for a tech review, but if I can’t understand it with native proficiency, someone else definitely won’t. Finally, I check for new terminology in the doc to see whether it’s defined through context or explicitly.

P: What’s your most important contribution as a reviewer?

J: I want to ensure the content is accessible and that it fulfills the intent of the educational goals. Not only must it flow, but it must be technically and semantically functional. And of course it has to be accurate. I like Google’s public review guidelines. There’s an emphasis on the intent of the reviewer. The goal of the review is to ensure that the code works as intended and any changes lead to improvement. My input as a reviewer should move the conversation forward while giving space to the author for maintaining their own voice.

P: What was hardest about learning Node for you?

J: Code shortcuts like the fat arrow. When I started learning it, ES6 was the new JavaScript standard. That included a number of syntactic sugar—language shortcuts—that would decompile into more regular structures. The problem for a new user like me was that the code was overly clever; concise but hard to unpack if you weren’t familiar with the shortcuts.

For me, that was a barrier to accessibility. In my current work, we have lots of people from nontraditional backgrounds. To me, that has really emphasized the need for creating maintainable code. Code doesn’t have to have perfect crystalline structure, or have the latest language constructs. It doesn’t have to be scholastically eloquent. It must be something someone else can read and understand the intent of. That is maintainable code.

P: What’s your involvement in the open-source community?

J: I feel strongly that if you use it, you should contribute back to it. I contribute as much as I can, while also having a 2- and 4-year-old and working a full-time job. I participate in issue queues and submit bug reports and patches, and I have a couple contributed open-source projects. I encourage my teams to do the same because the web we know and use today is built on open source software.

P: In your day-to-day role, you oversee and mentor other developers. What makes a good mentor?

J: To be available and to listen. To make sure those you’re mentoring have the resources to be successful and to let conversations go where they want them to. It’s about exploring difficult concepts. I also think teaching soft skills like code reviews, interacting with non-technical audiences and collaborating with others with different backgrounds is important. Engineers need to be able to distill technical concepts into non-technical language and do it in a way that doesn’t feel belittling.

P: You mentioned colleagues with nontraditional backgrounds. So much of web development is self taught. Any advice for new learners?

J: Have a passion project that you want to achieve. It doesn’t matter what it is -- it just has to motivate you. Learn what you need in order to succeed!