A Documentation Overhaul for an AI Startup
Reading Time: 3 minutes
The Challenge
In 2018, Texterity was contacted by a fast-growing AI startup looking for help with their documentation. This was four years before ChatGPT, but they were already pioneering AI-driven natural language data interrogation. Their team—five PhDs in the room, I was told —was packed with technical brilliance, but they were struggling to keep their documentation coherent and up-to-date.
Their Operations Manager explained the challenge. Documentation was fragmented across Google Drive and customer-facing CRM pages. They needed a structured, scalable documentation system that aligned with their Agile software development process. They explicitly rejected Confluence and SharePoint—being a developer-heavy team, they wanted tools that fit into their existing workflows. I was invited to return in a few days with a proposal.
The Insight: Docs-as-Code
At the time, I had been reading up on Tom Johnson’s Docs-as-Code methodology. The idea was to treat documentation like software development, using the same version control, workflows, and tools as developers, and leveraging GitHub for collaboration so that documentation evolved alongside the codebase. This approach would make documentation updates as seamless as software releases.
The team immediately saw the value—but now I had to pull it off! I had never used GitHub, Jekyll, or Markdown, so I had to learn quickly.
The Implementation
The first step was setting up the development environment. A techie friend installed Ruby on my PowerBook, and I installed Jekyll, the lightweight static site generator. For writing and formatting, I set up Brackets, a developer-style text editor for Markdown.
Next, I had to familiarize myself with GitHub, which was more than just a repository; it was a full version control system with its own branching methodology. I cloned Tom Johnson’s Jekyll folder structure to provide a solid starting point and created a staging site where documentation updates could be previewed before deployment. I also developed a custom CSS to fine-tune the documentation’s formatting.
With the structure in place, I set up a branching model: a main branch for production-ready documentation and a staging branch where edits could be tested before merging. Reviews and corrections by subject matter experts were handled through Git pull requests, following standard development practices. This allowed documentation updates to be reviewed and approved just like code changes.
There was a lot of trial and error along the way. I spent considerable time troubleshooting and refining the process, using Google and YouTube to find solutions to the technical challenges. Regular testing on the Jekyll staging site helped ensure that formatting and usability remained consistent.
Training & Adoption
One month in, I presented the system to the team at one of their lunchtime show-and-tell sessions. The reception was positive, although I felt like a student presenting to a room full of professors. But the fact that Docs-as-Code fit seamlessly into their Git-based workflow made it easy for them to adopt. Within a few weeks, the system was fully integrated into their documentation process, and updates became a natural part of their development cycle.
Conclusion
The hiring manager was pleased with the result. Documentation was now structured, versioned, and scalable. The AI team embraced the system because it aligned naturally with their existing development workflows. As for me, I gained invaluable experience, learning GitHub, Jekyll, and Markdown on the fly and proving how effective the Docs-as-Code approach could be in a real-world setting.
This project reinforced how aligning documentation workflows with engineering processes can transform technical writing from an afterthought into an integral part of development.