Documentation That Helped an Acquisition
Bacalhau is a distributed compute platform that lets developers run jobs on data wherever it lives, without moving it to a central location. When I joined, the documentation existed but lacked structure, and the developer onboarding experience was making it hard for new users to get started.
Applying the Diátaxis Framework
I restructured the entire documentation using the Diátaxis framework, organising content across distinct categories in Docusaurus:
- Tutorials for guided learning experiences
- How-to guides for specific tasks (like writing a SpecConfig or running Docker workloads)
- Conceptual documentation explaining the platform architecture
- API references for the technical specifications
Each category served a different need. A developer evaluating the platform needed the tutorial. A developer building on it needed the how-to guide. Mixing these together (which is what the docs did before) meant nobody could find what they needed quickly.
Redesigning the Getting Started Journey
The getting started guides were the highest-leverage change. I rewrote the onboarding path with practical examples so developers could run their first job with minimal friction. Every guide was tested against the live platform to make sure the steps actually worked.
This wasn’t about writing better prose. It was about removing every unnecessary step between “I just found this platform” and “I just ran a compute job on it.”
The Metrics
Documentation traffic grew from 10K to 47K views. Unique users grew from 200 to 6K. These weren’t vanity metrics. They reflected a real shift in how accessible the platform had become.
I also launched a Substack newsletter covering product updates, growing from 116 to 2K email deliveries. This gave the community a consistent channel for staying current with the platform’s development.
The Acquisition
Most significantly, I delivered the complete documentation for the Bacalhau v1 release. This documentation played a direct role in the company’s acquisition by Expanso.
When the acquiring team evaluated the product, the documentation was one of the assets that demonstrated maturity and developer readiness. Good documentation signals that a product is ready for a wider audience. It was one of the factors that made the acquisition viable.