The challenge

Scylla hosted all their docs in a single knowledge base. At the same time, development teams had docs in different spaces, such as wikis or repositories, but they were not discoverable from the main site.

Besides, the technical writer/developer ratio of the company is limited. This makes keeping the documentation up to date challenging without the contributions from the development team. However, the documentation did not always reflect the latest changes.

Working alongside the product team, we helped Scylla design and implement a documentation toolchain that projects can install next to their code to create documentation sites. We made their docs easier to write, read, and find by following the same processes and working with the same tools developers use to program code.

In the talk "Documentation Communities: Sound Strategy or Documentarian's Gambit?", Laura Novich presents the solution and refers to this approach as docs in tree.

Instead of having one knowledge base with all the information, now each project maintains and owns its documentation site. Ultimately, we aggregate all the individual sites in the public developer portal docs.scylladb.com.

Making docs easier to write

Now, Scylla developers write all their docs in plain text format in the Git repository where they code. This change lets them update the documentation as soon as they release new features following the same Git workflow.

With the new documentation toolchain, devs can preview the documentation locally. When the content is ready, they submit their docs changes in a pull request, together with their code. Once the pull request is accepted, we have automations in place to publish the product documentation.

In addition, we shared with the development teams guidelines with examples and templates they can use to contribute new content to Scylla docs.

Making docs easier to maintain

We streamlined the process for reviewing and updating documentation. Previously, any changes required reviewers to manually build the site on their local machines to check for any layout issues. This step was often skipped, especially for pull requests that included more than just documentation updates, leading to unnoticed errors until a new version was released.

Now, the updated toolchain automatically builds and tests the documentation with every pull request, eliminating the need for local builds. This ensures any changes to the docs are verified for issues before merging.

To further simplify the review process, we've implemented an automatic system that shares a preview link of the documentation directly in the pull request comments. This allows reviewers to easily view changes in real-time, without the need to download and build the documentation locally.

Additionally, we've leverage automation to autogenerate reference documentation from the code, including tables of properties, CLI documentation, and OpenAPI specifications. This integration not only saves time but also ensures that our documentation is consistently accurate and up-to-date with the latest codebase developments.

Making docs easier to read

We developed a custom theme and extensions that all the sites share to have the same look and feel.

If the content is incorrect or someone does not find what they were looking for, it is possible to report an issue on GitHub or open a pull request from the same documentation page.

Besides, all the documentation sites support multiple versions, so readers can refer to the specific documentation of the software they are using.

Making docs easier to find

All Scylla documentation is centrally accessible via the portal at docs.scylladb.com.

A unified search integration facilitates comprehensive cross-site searches, allowing users to quickly find relevant information with minimal effort.

Tech stack