Last year we took on a project to overhaul our docs and saw an opportunity to overhaul the way we work together. A few weeks after we hired our first Technical Communicator, we packed our bags for San Francisco to spend a week with the Dev team who created the API docs that were released alongside v.zero. We started by assessing our audience and concluded that there are two distinct types of customers who use Braintree’s support docs: technical and non-technical.
Braintree's internal organization is similarly divided, with Product teams focused on the technical development of the gateway, and Operations teams focused on business-oriented aspects. Historically, we’d treated our two sets of documentation the same way; we managed our API docs and support articles in separate apps, with different tools, and minimal collaboration.
Our new approach eventually pulled both sets of docs into one app, housed within the same Github repository and managed by a combination of a Chicago-based Operations team and a San Francisco-based Development team. Now, everyone has a vested interest -- whether they're writing code or prose -- and, in working together every single day, we’ve started bridging the Ops/Product gap with more open communication. In short, uniting our docs has united our teams and fueled our mission toward domination through documentation.
We’ll share more in future posts, but here are a few critical things we’ve learned along the way:
Communication is hard
In August of 2011, there were fewer than 40 Braintree employees. Operations and Product teams worked much more closely with each other in part because we were all located in the same office. As we’ve grown, we’ve opened offices in locations across the globe. Operations teams are still primarily based out of Chicago, whereas Product teams are spread across multiple locations.
Feedback is incredibly important to the development and support of our product. Like many companies, we’ve experienced growing pains in communication as a result of team size and proximity to each other. Some of the ways we’ve worked to improve company-wide collaboration include:
- Publishing an internal Weekly Update for quick information on products, team announcements, and merchant kudos
- Using Github pull requests to discuss docs improvements and ideas
- Making content more centralized/easy to find
The quality of product documentation impacts everyone
We conducted our first employee survey on docs usage in May and found that 93% of respondents regularly use our internal documentation in their day-to-day tasks. This internal wiki (Confluence from Atlassian) is also used to develop policies and procedures for supporting our customers and so it needs to be accurate and easily searched. However, the amount of information contributed to the wiki has grown exponentially over the past couple years, which has made these two factors a challenge; accuracy and searchability came in at 3.5 and 3.2 out of 5. These results confirmed what we already suspected, and we are actively working on implementing tools and procedures to improve the quality of this resource.
Merchants and developers rely on Braintree’s public documentation to build their own business plans and products, and so we’ve put the majority of our effort over the past 11 months into improving the quality of that content. We’ve released an entirely new set of support articles geared toward our Business Operations audience, and we’ve overhauled our API docs to include a comprehensive server-side reference guide as well as more concise getting started and integration guides. We’ve focused on a few prime components in this iteration:
Tone and consistency
We began to formally define the tone we wanted our public documentation to have when we started creating new support articles last fall, and that tone naturally carried over to the API docs. We created a product template to help ensure that teams were adding new information in a more consistent format, and we relied heavily on peer reviews for quality assurance.
Feedback
The Docs and Support Dev teams regularly review the feedback we get from merchants and developers and create Trello tasks based off of it. Since we introduced the feedback form at the end of January, we’ve completed nearly 100 tasks directly related to feedback -- from typo and broken link fixes to the creation of entirely new content or code snippets.
Accuracy
Product timelines move quickly, so keeping up with the latest releases and ensuring that documentation is accurate has been our greatest challenge. To help keep us up to date, we’ve built automated tests that verify our reference content against our internal services. Also, when we launch new products, we release private documentation for beta users so we can perfect our content in production before we publicly launch.
Dedicated resources are key
It’s our belief that we can improve your experience with Braintree by providing quality documentation. Good public-facing docs will help you help yourself; good internal docs help our support teams better help you. This was the impetus for the creation of a dedicated Docs team, and it’s the driving factor behind our work today.
We regard documentation as product in and of itself, and have turned that focus into an opportunity to foster more and better collaborative efforts between our own Operations and Product Development teams.
We know we’re not perfect, so we’d love your suggestions and feedback. Click on the "Give us some feedback" link at the bottom of every docs page to provide input on a particular article or send us a note at support@braintreepayments.com if you have general ideas or suggestions.
What’s next?
We’ll continue to share more about our journey toward docs domination in a series of posts. The next post will cover how we restructured our docs content and why.