Articles by Brandon West

Brandon West

As Director of Developer Relations for SendGrid, Brandon's focus is on empowering developers to build things, gathering feedback for new features and improvements, and fostering a cooperative developer community for anything that needs email integration.

Follow Brandon

4 Common Antipatterns to Avoid in Your Documentation

Brandon West Technical
Apple iTunes RSS

Design patterns are powerful things. They help us short-circuit a lot of trial and error by relying on the past experience of others. They provide a common lexicon for communicating complex concepts. And, applied thoughtfully, design patterns improve our understanding of our craft as well as its effectiveness. And you’ll notice I haven’t mentioned software. Design patterns exist for many disciplines, and the core concept originated in architecture. One of my personal favorite pattern languages comes from the book Presentation Patterns, and it describes common solutions for problems encountered when preparing for and delivering technical presentations to audiences. Teachers also often use pedagogical patterns. What Is An Antipattern? Just as patterns are good solutions to common problems, antipatterns are bad

Technical Debt is Not a Bad Thing

Brandon West Technical

If you work around developers, you have probably heard the term “technical debt.” It’s a widely used metaphor that is useful when considering how to build and maintain software. The term was coined by Ward Cunningham, a computer scientist who created the idea of a wiki and contributed heavily to the development of object-oriented design patterns. But even though the metaphor is widely used in the world of software development, I meet a lot of people who don’t understand what technical debt is and why it matters, or people who are completely unfamiliar with the term. What Is Technical Debt? Our understanding of a software problem evolves over time, and our code should reflect our current understanding of the problem.

How I Evaluate A Developer Evangelist Candidate

Brandon West Community

Interviewing a developer evangelist is tricky because there’s a variety of hard and soft skills required. An evangelist has to be a strong developer, but also has to wear many other hats, work horizontally across departments, and be an engaging and helpful participant at events. If you’re wondering what the day-to-day duties of an evangelist might look like, check out the blog post I wrote after my first year as an evangelist. Standout Qualities I don’t give candidates an engineering test. I don’t care if they know which sorting algorithm is the fastest and I’m not going to ask someone to implement malloc or put any code on a whiteboard. What I will do is ask questions that provide an

Why Mind Maps are Awesomesauce

Brandon West Best Practices
Mind maps

About a year ago I started using mind maps to help me organize presentations, meeting topics and blog posts and I’ve found that it works really well for me. Mind maps help me take broad, abstract ideas and turn them into concrete, real world examples that I can use to help tell a story. What is a mind map? It’s basically a branching diagram. From wikipedia: A mind map is a diagram used to visually outline information. A mind map is often created around a single word or text, placed in the center, to which associated ideas, words and concepts are added. Major categories radiate from a central node, and lesser categories are sub-branches of larger branches. Categories can represent

Dirty Socks and Technical Debt

Brandon West Events
Socks drying

Last month I spent two weeks traveling to Mexico City, Bogotá, São Paulo, and Rio de Janeiro with Geeks on a Plane Latin America. This was my second GOAP trip; my first was last year’s trip to Eastern Europe. GOAP is an amazing professional and personal experience and I highly recommend it to everyone. Once our group of geeks arrived in Mexico City, I discovered I forgot to pack socks, so the only pair of socks I had with me were the ones I had on my feet when I left home. Not a big deal, as I figured I’d just buy a few more pairs when we had a few free moments. What I had forgotten to account for

Why We Open Sourced Our Documentation

Brandon West Product, Technical
SendGrid docs

I talk a lot about docs, because it’s important to me and important for the success of a product. You can read some of my thoughts on what makes good documentation and using Jekyll to create documentation. One of the goals I set last year when I was asked to take over the documentation was to eventually open source it. I’m happy to say that this week we flipped the switch and anyone can now view and contribute to the source for our documentation. Check out the SendGrid Docs repo on GitHub. Good documentation allows feedback from readers so they can point out inconsistencies or typos and have them addressed quickly. Even better is providing a feedback loop where those

Creating Sustainable Documentation with Jekyll

Brandon West Company, Technical
Dr. Jekyll and Mr. Hyde

I’ve spent a big part of the last year working on documentation for SendGrid. I’ve learned a lot of things. You can read about how we broke down the problem of documentation at a high level and why documentation is critical for success in Cheat Codes for Good Documentation. Below you’ll find the path we took, from the early days through last November’s switch to the current system, based on Jekyll. Most of what I’ll recommend applies to documenting an abstraction layer, e.g. an API. Scope of SendGrid’s Docs Just for context of what SendGrid’s docs look like, here is the output of a linklint check. 35 directories with files 6 default indexes 230 html files 1 image file 77

Building a Conceptual Framework: How to Design Programs

Brandon West Technical

If you want to learn to code, it’s important to start building a conceptual framework so you can effectively communicate with developers. The book I recommended in that blog post, Simple Program Design, is a great start and will give you the basic tools you need to get going. You can go through the entire book and all the exercises relatively quickly. Most people that are interested in learning to code want to dive in and make something work, and the goal of building a conceptual framework is to make sure you know how to swim first. But Simple Program Design isn’t very heavy on computer science. You don’t need to be a computer scientist to learn to code but

Cheat Codes for Good Documentation

Brandon West Best Practices, Technical
Still my favorite Programming Manual
Still my favorite Programming Manual

The Best Programming Manual

Everybody, especially developers, loves working on documentation. They understand the importance of docs and its impact on customer adoption and customer experience, and they always consider docs when planning and releasing code. Wait, why are you laughing?

Many companies have some kind of trouble with documentation. Lots of common problems make docs difficult to wrangle; information gets out of date or lacks completeness, the content is poorly organized or inconsistent, readers can’t find what they’re looking for, and code samples might be broken. If you walk through most engineering departments and ask for volunteers to help update docs, you’ll be met with silence if not outright derision.

The truth is that there are no cheat codes for creating a culture that values documentation or for creating quality content, but I’d like to share some practical things I’ve learned while trying to do just that at SendGrid, and hopefully give you a few extra lives (or at least some extra quarters) for your game.

Read More ›

Two Years: A Long Time as an Evangelist

Brandon West Company
Two years of lanyards

24 months. It doesn’t seem to add up; “Developer Evangelist” still seems like the job I just started. I guess after writing code for a third of my life, that’s true. Learning and doing new things keeps me busy enough that I haven’t paid much attention to time sneaking past me. You could say that a lot has happened in those two years and nobody would call you a liar. SendGrid has raised more money, quintupled the number of employees, hit a couple bumps in the road along the way and continued a rapid pace of growth. When they offered me a job two years ago, I could tell this was a great company with a lot of potential. It

Learn to Code: Build a Conceptual Framework

Brandon West Technical

When we last talked about learning to code I recommended learning program design before jumping into choosing a program language and writing code. The hardest thing about learning new tech is getting the conceptual framework. My question may be simple, but I don’t know how to ask. — Sarah Allen (@ultrasaurus) July 4, 2013   Sarah Allen is speaking about complex systems in general, but her tweet gets right to the heart of why it’s important to learn flow control structures, simple data modeling, and program design if you want to be a developer: these tools give you the conceptual framework and vocabulary needed to discuss programming with other developers, which is necessary for you to be able to effectively comprehend

Advanced Statistics Available Via API

Brandon West Best Practices, Product, Technical

Earlier this year we added a few beta statistical reports that show you the location, device and browser information, and ISPs of the recipients that click and open the emails you send. We have been working hard on improving these reports and integrating them more fully with the rest of our offerings. You can now retrieve these statistics via our Web API so you can crunch the numbers as you see fit or display them in your application’s dashboard. Head over to the Advanced Stats API documentation for more details and example calls. Happy coding!