SingleStore Scales Documentation 90% Thanks to Paligo’s Content Reuse

Intelligent applications are challenging to build: they need analytics to know what happened in the past, and vector and full-text search to predict what will happen in the future. And all apps require transactions. SingleStore is the most performant solution to power all three at scale. By combining transactional and analytical workloads in a single unified platform, SingleStore eliminates unnecessary data movement that leads to performance bottlenecks.

Capable of scaling to any size while handling SQL, JSON, full-text and vector search workloads, SingleStore is the only database customers ever need. They meet you where you are to grow alongside your apps, user base and business challenges — scaling from one to one million customers. The ability to transact, analyze, and search all types of data at lightning speed means no more slow to your flow. SingleStore helps organizations of any size build and deploy cutting-edge applications quickly, for faster, more agile decisions.

SingleStore’s simplicity, scalability and flexibility are why many of the world’s largest enterprises choose them to deliver exceptional customer experiences, including Adobe, CARFAX, Cigna, Cisco, Comcast, Dell, EY, GE, Goldman Sachs, Hulu, IMAX, Kroger, LG, RBC, Samsung, Siemens, SiriusXM, Sony, Tata and more.

SingleStore creates and manages multiple versions of its documentation in support of its Helios and self-managed database products. In 2019, the Technical Documentation team was using a custom Docs-as-Code solution based on Markdown files and GitHub. A local content server allowed Technical Writers to visualize the updates to their Markdown files. When happy with the updates, the associated Markdown files were then checked into GitHub. To publish these updates, a Technical Writer kicked off a publishing process that pushed the updates to production. While this solution managed eleven different versions of the documentation, the number of unique Markdown files was growing by approximately 10% with each major release of SingleStore. The 100% growth from version to version was due to the need to clone the documentation from the prior major release to make version-specific updates for the new major release.

Chris Lugris, Senior Manager, Technical Documentation, expressed that this custom solution made their documentation arduous to work with, difficult to maintain, and inflexible. This solution also imposed a specific structure on the documentation, where content needed to reside in one of three sections: conceptual content; guides, all of which followed a fixed template; and reference content. While the amount of content continued to grow with each major release of SingleStore, the number of new features that required documentation was also accelerating. Over time, updating links became challenging and error-prone, and, while each version of the documentation shared much of the same content, there was no facility for reusing content. While this solution had worked for a while, it was starting to show its limitations.

With the release of Singlestore version 7.3, the team saw an opportunity to change how they managed the documentation.

I think what really drove this decision is that we could see how much content we were going to be dealing with. While we were really only focusing on documentation for SingleStore (then MemSQL) versions 6.5 to 7.1, it was becoming a real challenge to maintain. When a new Markdown file was added, there was a good chance that it had to be replicated across each version of the documentation. Sometimes content would skip a version of SingleStore, sometimes content would be retired from a version of SingleStore, and sometimes content would only apply to earlier or later versions of SingleStore.

The Technical Documentation team needed a solution that allowed them to manage multiple sets of documentation that was continuing to grow, for a product that was rapidly evolving.

While the Technical Documentation lead at the time was already familiar with Paligo, alternative solutions were also surveyed and compared against the team’s requirements, including the solution that powered the marketing site.

There were several key requirements for a new content management solution, where the ideal solution needed to help the team:

1. Support multiple documentation versions
2. Manage documentation growth
3. Document an evolving product
4. Reuse content

After some due diligence and “tire-kicking,” the team found that only Paligo fulfilled all of these requirements.

At the time, there were roughly 1,200 individual Markdown files, and importing, organizing, and cross-referencing everything posed the greatest challenges during the migration process. As Lugris recalled, “As we didn’t know how to effectively create cross-references amongst the set of newly-created topics, topics that were once Markdown files that contained proprietary links to other Markdown files on a filesystem, we really needed to lean on Paligo Support to help us migrate and link everything.”

While the Technical Documentation team managed migrating the documentation, they enlisted the help of their Web Dev team to find the best solution for publishing it. The first approach involved Paligo’s native ability to publish a set of documentation as a complete Web site. The Web Dev team developed a method to consolidate and repackage each set of documentation, one for each version of Singlestore, into a single Web site, complete with SingleStore’s look and feel and a drop-down for viewing the desired set of documentation. While effective, it wasn’t optimum.

A developer on the Web Dev team later evaluated the Paligo API for this task, where he learned that he could use this API to pull the “raw” content directly out of Paligo. This approach greatly simplified the overall publishing process, and is the method that’s in use today.

With Paligo, the team has effectively accelerated content creation while simplifying overall content management. Once all of the documentation was migrated to Paligo, Lugris was able to determine that some parts of it would only vary by approximately 5% from version to version.

In the case of the deployment guides, the available methods for deploying a SingleStore cluster were already well documented. After scrutinizing the associated content, Lugris and a fellow Tech Writer uncovered that it was approximately 95% the same across all versions of the documentation. The Tech Writer was able to define the exact content that was common to all versions of the deployment guides, and she distilled it all into a handful of core topics in Paligo. Now, with each major release of SingleStore, only these core topics need to be updated, and only with the information that’s specific to the release.

Thanks to Paligo, content reuse and version-specific content tagging has replaced the need to clone a set of Markdown files for each major release of SingleStore. As the number of major releases has since grown from one to nine, Paligo has helped keep the topic count low by allowing the team to create new topics only when required.

Another Paligo feature Lugris said that the team uses frequently is publication and topic branching. When a Product Manager requests changes to the documentation’s content or structure, a Technical Writer makes the requested updates to branched publications and topics. These branches are then published to staging for review. Once approved, the branched topics are merged back into their parent topics, and the associated structural changes are made to the production publication. These collective updates are then pushed to production.

While this approach to using Paligo’s branching feature is somewhat unique, Lugris noted that it works well for the team, as it is a branching model that they’re all familiar with. In addition, the bespoke publishing process can push these publications and topics to either staging or production, regardless of whether they’re branched, or where they reside in Paligo.

Today, SingleStore’s Technical Documentation team manages two separate publications in Paligo:

• Helios, which contains one set of documentation for SingleStore’s cloud-based database product
• Self-managed, which currently contains nine sets of documentation, one for each version of its self-managed database product

Around 1,600 topics are used and reused among these two publications. When published, this translates to around 15,000 static Web pages.

Thanks to Paligo, we’re currently managing around 1,600 topics vs. managing around 15,000 individual Markdown files had we continued with the Docs-as-Code approach. By switching to Paligo, we’ve effectively reduced the number of managed topics by about 90%.

Today, the Technical Documentation team can create a set of documentation for a new SingleStore version in minutes, and manage specific version updates faster and more easily than ever before.

It’s really funny. With Paligo, we kind of turned the equation on its head. We’ve been able to create the most documentation that we’ve ever had, and do so with only a fraction of the content than we would have typically needed to manage.

Paligo is helping the Technical Documentation team make the required changes faster, and the team strives to make their documentation, as Lugris noted, “used and useful” for and by SingleStore’s customers.

His advice for other companies who are looking at Paligo to improve how they create and manage their technical documentation?

Paligo is a great tool for documenting a core set of features that span multiple versions of a product, especially where these features evolve within, and across, product versions. Paligo has allowed us to handle these feature variations with ease, and do so across multiple versions of our documentation.