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 thoseRead More ›
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 77Read More ›
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 butRead More ›
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.
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. ItRead More ›
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 comprehendRead More ›
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!
Good news, everyone! We’ve open sourced an officially supported Perl library for SendGrid. We have used this library internally for some time and decided to release it for the community to use and improve. The readme on github has more information on how to get things going, but the code for sending a simple email and using some SendGrid features looks like this: Packaging this library and getting the tests to run was fun since I had never touched Perl before. There is tons of good material out there regarding Perl, as you would expect given its history and popularity. Like any language, there are several different ways to accomplish the same tasks, so I got caught up aRead More ›
Evangelists arrive at airport gates with just enough time to board. They have stockpiles of frequent flyer miles and memberships in a variety of hotel loyalty programs. They know exactly how to pack their bag depending on where they’re heading and for how long. I asked a few fellow road warriors what ends up in their travel kits when they prepare to head out. The most common items are a supplemental battery pack like a Mophie Juice Pack or Zagg Sparq for those moments when your phone is at 5% and you’re trying to map your way back to the hotel, a variety of display adapters for plugging in to monitors and projectors, a mobile hotspot, a notebook, and someRead More ›
Today SendGrid is excited to announce our new and improved documentation! Some of the highlights of the new system are: Quicker load times Improved navigation and organization More relevant search results Increased legibility Cleaner presentation of code samples Ability to toggle between JSON and XML examples The new system will allow us to collaborate on updates and changes much more quickly, and we hope that the changes will allow developers to find what they need quicker than before. We’d love to hear your feedback on how you like the changes or what we can do to make things better, so feel free to email us.
Over on his blog The Pug Automatic, Henrik Nyh has published a great tutorial on using categories and unique arguments to add metadata to your messages in Rails, which you can then see data in the email activity log or on in event API posts. Read More ›
Last weekend after the Lone Star Ruby Conference in Austin, a group of developers gathered at Capital Factory for an overnight hackathon with a focus on communications. In addition to the awesome support and space donated by Capital Factory, the event was put on by Context.io, Twilio, SendGrid, and Searchify. The prizes were big ticket items, with first place taking home a MacBook Pro with Retina Display, and the runner-up getting a Thunderbolt Cinema Display. There were also prizes for the best use of Twilio and the best use of SendGrid. Read More ›