How We Automated Our Technical Documentation to Increase Developer Velocity.
Many engineers experience a love-hate relationship with Technical API documentation–any supplement that helps others use and understand code. As we scale our engineering teams at WHOOP, we view documentation less as just another checkbox in the development process and more as one of the key drivers to maintaining a lightning-fast development velocity. While helpful when jumping into new repositories or during stressful moments of debugging, documentation can be tedious to maintain, time-wasting to find, and frustrating to share. Enter Tech Docs.
Like all our Infrastructure tooling, Tech Docs has its very own logo–a logo that is unapologetically out of style.
Automating Generation
Tech Docs’s primary purpose is to take the work of creating and maintaining documentation out of the developer’s hands. We accomplish this automation by coupling an API deploy with documentation generation. With this marriage in place, developers can instantly view any updates they trigger in the documentation immediately after those changes deploy. This connection guarantees up-to-date documentation and takes the burden off the developer to go back and manually create documentation. In the fast-paced world of software development, many follow documentation blindly, and, with Tech Docs, developers can continue to put their trust in documentation with the added assurance of automation. To accomplish this automation, we leverage Swagger to expose a service’s OpenAPI Specification that we then bundle via Redoc immediately after a developer deploys an API. We then serve that bundled HTML via our user-friendly UI.
Sample documentation for Tech Docs, generated via Swagger, OpenAPI, and Redoc
Increasing Discoverability
While automatically generating documentation is worth hours of manpower, Tech Docs is worthless without a quality user experience. To optimize our user flow, we created a BootstrapVue user interface to allow users to browse documentation, search by service name, and filter by software team. The interface serves all our API documentation for WHOOP in one place, therefore, minimizing time wasted trying to find documentation from various sources. We also display API service metadata, including each service’s most recently deployed branch and build so that developers can match their documentation with a specific deployment. Additionally, we store every documentation revision for all of our services. This history allows developers to access older versions, including that of any branch any developer ever deployed. Within a service’s documentation, we also support endpoint search to further expedite the process. While each feature of this interface may seem simple, every addition is a drop in the bucket that we made sure to fill to the brim with positive user experience.
Tech Docs, our developer documentation portal, displays information about all our documented services at WHOOP
Enabling Collaboration
The drive to enable developer collaboration is one of the most motivating forces behind creating robust technical documentation. WHOOP divides its software organization into product teams, each of which collaborates regularly to create the standout features you experience as a WHOOP member. Being able to jump into another team’s repository and quickly understand the different facets of the code is paramount to increasing development efficiency, a value that drives why we operate within a monoglot developer ecosystem. We created a standard format for all API documentation, so Tech Docs removes the need for developers to acclimate to varying documentation styles and thoroughness. Additionally, a Tech Docs documentation file includes page fragments that help developers navigate to a certain documented endpoint. This feature allows developers to send each other a direct link to a specific endpoint rather than throwing one another blindly into an entire service’s documentation, which can contain many documented endpoints depending on the service.
Moving Forward
At WHOOP, we felt our documentation was disorganized, nonuniform, and hard to share, pain points that exist not only here, but across the software industry. Having previously adopted positive software organizational principles such as making our codebase a monoglot system, we capitalized on this standardization to create Tech Docs. By creating an engine able to generate documentation for all Java APIs, the Application Infrastructure Team minimized developer documentation pain with a touch of clever automation, a focus on discoverability, and a priority of developer collaboration. The temporary lift of Tech Docs development is a small price to pay for automatic, discoverable, and shareable documentation for years to come, and we will continue to look for ways to create powerful tooling rather than hamstringing processes so that all developers at WHOOP can focus on the fun stuff.
If you are interested in building infrastructure at WHOOP check out our open positions.