Documentation is often someone's first experience with a product.
It's where developers learn how to integrate an API, security teams understand policy configuration, and legal teams explore licensing workflows. When documentation is easy to navigate and stays current, customers spend less time searching for answers and more time using the product effectively.
While FOSSA has historically made continuous investments in keeping our documentation current and relevant, our platform has added significant capabilities in recent years. This led us to take a hard look at whether our old way of doing documentation kept pace with our users’ needs.
It also prompted an important question: What would it look like to completely rethink the documentation experience?
Those conversations paved the way for FOSSA's first Hack House, which took place earlier this summer. Hack House 1.0 was a four-day, cross-functional sprint dedicated to creating documentation that is easier to navigate, easier to maintain, and ultimately more valuable for every customer.
Investing in the Foundation
After a series of conversations about the prior state of our documentation, our team came to the conclusion that investing in a comprehensive overhaul was the right move for our customers. This started with building the right foundation: documentation infrastructure that could grow alongside the product for years to come.
The team aligned around five guiding principles:
- Own the documentation stack with Next.js and Markdoc
- Build a production-ready replacement, not a prototype
- Audit content before polishing it
- Organize documentation around products and customer tasks
- Create a shared glossary so the entire site speaks the same language
Four Days of Focused Collaboration
Hack House brought together members from our engineering, customer success, go-to-market, and product teams into one shared effort.
By Friday morning, the first Next.js scaffold was already running.
The team began migrating content from fossapedia, FOSSA's GitHub repository containing the source for our ReadMe-powered documentation. Treating documentation like code meant every change could be reviewed, versioned, and deployed through the same workflows our engineering teams already use.
At the same time, we built an automated OpenAPI synchronization pipeline so API documentation always stays aligned with the latest product changes.
Rather than migrating pages manually, the team also developed a Claude-powered "move-doc" workflow that helped transform existing content into the new structure while validating it against the codebase.
To keep everyone moving in parallel, we relied on Git worktrees and a dedicated restructure branch. Everyone could work simultaneously without blocking one another or creating merge conflicts.
During the second half of the sprint, attention shifted toward the customer experience.
We re-organized docs navigation around products and common workflows to make it as intuitive as possible for our users. We improved the quality and consistency of product images via a Playwright-based screenshot pipeline. And we rolled out automated link validation to ensure customers could continue finding the documentation they depended on.
By Tuesday, the new documentation platform was ready for a company-wide demo.
Hack House’s Customer Impact
As we reflect back on the Hack House 1.0 experience, our team is proud of how our work created significant and concrete improvements for our customers.
The new documentation offers a faster, more consistent experience. Behind the scenes, the workflows established during Hack House make it easier than ever for teams across FOSSA to contribute, review, and maintain documentation as the product evolves.
Customers can expect to see a range of specific enhancements when they view our documentation today, including:
- Product-focused navigation instead of one large "Welcome" section
- Task-based organization that helps users find answers faster
- Native API reference with runnable examples in curl, Python, and Go
- Consistent terminology supported by a shared glossary
- Mermaid diagrams that stay maintainable as the product evolves
- Automated, standardized screenshots
- Better search with Command+K
- Infrastructure that keeps API documentation synchronized automatically
Behind the scenes, those improvements are powered by tooling that makes documentation easier for every team at FOSSA to contribute to.
Hack House By the Numbers
Over four days, the team accomplished:
- 420 commits
- 191 pull requests merged
- More than 200 documentation pages migrated and reorganized
- 351,000 words reviewed
- 352 centrally managed images
- Six cross-functional contributors
Perhaps more importantly, the project established repeatable workflows that will continue benefiting every future documentation update.
You can experience FOSSA’s upgraded documentation by visiting our docs homepage. We certainly welcome your feedback, comments, and questions as we continue to work to make our docs as intuitive and valuable as possible. You can get in touch by emailing hello@fossa.com
Built by: Sara, Chelsea, Barbu, Joseph, Dave, and Jason during FOSSA's first Hack House.