We Are Hiring

Why We Open Sourced Our Documentation


Posted on

SendGrid docsI 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 readers can see that their issue has been noted and track progress and see how it fits into the rest of the work to be done. Better still is a place where readers can jump in and submit their own edits if they feel inclined.

SendGrid docs pull request

Documentation is also something that a lot of companies struggle with. I’ve had meetings with several startups to talk about documentation practices and share some of what I’ve learned, as well as speaking about docs at a few conferences. Sharing our code is another way to share documentation-related knowledge. The better all of the docs for all of the things are, the better off the developer community.

I expected some resistance to the idea of open sourcing the docs from within the company, but I was completely wrong. Every person I spoke with from co-founders to sales to engineering to support was in favor of the idea. So much so that I didn’t ask permission (so if my bosses are reading this, thanks for your support!)

In the end, I expect this move to make our service easier to use, which is the point of documentation in the first place. Open source documentation feels like the next step in creating good documentation.

Tags:


As a Developer Evangelist 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.

3 thoughts on “Why We Open Sourced Our Documentation

  1. Brandon, the lucky thing is…you don't have a boss! But, you do have coworkers, team members, colleagues, peers. And we're all on board. Awesome work, and congrats on reaching this milestone.

    - TF

  2. Pingback: GitHub Hosting Documentation for Dozens of APIs

  3. Pingback: Tips to Embrace Your Developer Community

Leave a Reply

Your email address will not be published. Required fields are marked *

You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <strike> <strong>