Human-First Documentation: Braze Announces Open Sourced Docs

Everything Braze does—every automated process, every metric and bit of code—is done with humans in mind. (We even made “Humanity in Action” the theme of this year’s LTR customer engagement conference.) But what that looks like differs from team to team and department to department. For us, the Customer Education team, the question we asked ourselves was: How do you put the “human” into documentation?

Our answer? We made the decision to open source our Braze Docs GitHub Repo in order to foreground a living, person-focused approach to technical dochumantation.

Introducing Open Sourced Braze Documentation

Every Braze customer has different uses for our products and different needs—they take advantage of varying integrations and leverage their own unique combinations of Braze platform features, Braze Alloys Technology Partners, and a lot more! And because each user experiences and integrates our product differently, we wanted to be able to capture all those experiences (and the learnings that come with them) in our documentation.

The benefits that come with open source software are numerous and can also be applied to open source documentation—especially if you think of documentation as a product. Some of the major upsides include:

1. More Gets Done. Faster.

Braze services multiple messaging channels using multiple SDK integrations. On top of that, we’re constantly updating, adjusting, and improving product features to ensure that our customers have the best possible user experience. That means there’s a lot to keep up with when it comes to documentation, but with open source docs it’s something we can all work on together. Ideally, we’d love to see the volume of improvements to our documentation double on a per-month basis; there’s nothing more satisfying than an empty “Issues” tab!

Braze partner SendGrid has proved that this kind of velocity is possible: In fact, their 2017 Hacktoberfest increased their GitHub contributions by more than 3,500%! (We actually worked with SendGrid to help plan our transition to open source documentation—thank you, SendGrid!)

2. An Expanded Knowledge Base with More Perspectives (Yes, that means you!)

Users aren’t just users and documentation shouldn’t be about us telling you what you do with our product. At its core, it should be a conversation where we discuss the capabilities and nuanced of the Braze product and how to make the most of it to provide a better experience for your customers and reach your business goals. Plus, there are a lot of experts out there who are passionate about messaging channels, customer engagement best practices, and troubleshooting...who may also want to build their GitHub portfolios. Who are we to deny them that opportunity?

Here’s the key thing: We really, really want your input on our product and what it can do. The use cases for Braze and its features are endless—and you’d be surprised how often it is that customers are the ones to highlight to us new things they’ve found to do with it. When you have such a powerful, flexible product, our “product users” are really “contributors” who constitute an incredible resource when it comes to documentation. Which leads us to the next benefit...

3. A Closer Relationship with All of You!

Our users are smart. Their teams are smart. And the truth is, it takes a village to build a product that works for the village. Open sourcing our documentation gives all of you a new, targeted way to communicate with our internal teams...and to become part of the extended Braze family. We depend on you to tell us what you need from documentation—so tell us!

4. We Get to Celebrate Hacktober!

To kick off our celebration of open source documentation—and our new relationship with all of our “contributors”—we’re hosting our first ever documentation Hacktoberfest. As part of the festivities, we’re hosting a series of internal and external activities. If you contribute to our repo during Hacktoberfest (that is, from October 1–31), you’ll be eligible to receive Braze and Hacktoberfest–themed prizes like custom pins and t-shirts (Who doesn’t want our beloved mascot Torchie on a tee? I know I do…)

Any contribution to our repo is valuable, no matter how big or small. So we wanted to lift the barrier to entry for you. All you need to do to get involved—even if maybe you’re less than entirely tech savvy—is to take five minutes out of your day to…

• Make a GitHub account
• Sign our Contribution Licensing Agreement (CLA)
• Choose the page you want to edit (You can do this right from our Docs site! We have fancy buttons at the bottom of our pages that will take you right to the appropriate file on GitHub!)
• Click the “Edit” button and make your changes
• Submit your change for approval

After that, our docs team will review your proposed change, adjust it if needed, and then approve it! It’s that easy. You’ll have made our documentation better, helped others to use Braze more effectively, and possibly gained a new hobby or skill. (Not to mention the fact that you’ve increased your chances of getting a Torchie tee…)

Anything Else?

Creating and maintaining useful documentation is a team effort. With the introduction of open source Braze docs, it’s easier than ever before to be a part of that team. So take a minute out of your day and join us at our GitHub repo—we can’t wait to see what you do!