The client
Scylla is a big data database that powers applications with ultra-low latency and extremely high throughput.
Scylla NoSQL is trusted by a rapidly growing number of global brands, including Discord, Disney+, Medium, Starbucks, and hundreds more.
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.
The solution
Working alongside the product team, I 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 also refined the documentation revision process. Before, reviewers had to build the site locally to ensure the changes did not break the layout. Since most pull requests do not cover only doc changes, this process was often overlooked. Therefore, issues with docs were not detected until the next version reached production.
Now, the toolchain builds and tests the docs on every pull request.
Besides, we automatically share the preview link in a message so that reviewers do not have to download and build the changes to see what's new.
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 the docs are discoverable from the portal docs.scylladb.com through product cards.
Additionally, readers can search across all documentation sites from the same search box.
Tech stack
To achieve this workflow, we used the following technologies:
- Markup language: Scylla Docs support both restructuredText and Markdown. We choose these two markup languages since technical writers prefer the first, and the second is most known and flexible for developers.
- Sphinx: Converts restructuredText and Markdown to HTML. Sphinx also has directives and extensions to add additional formatting options.
- Custom Sphinx Theme: All Scylla documentation projects share the same look and feel. This theme also adds a set of custom functionalities available to all projects.
- GitHub: Hosts the code, docs, source files, and issues of Scylla's projects.
- GitHub Pages: Hosts the production HTML version of the docs.
- GitHub Actions: Builds, validates, and deploys the documentation to GitHub Pages.
- AWS Amplify: Builds the documentation for every new pull request.
- Expertrec: Crawls all the documentation sites to offer a unified search experience.
For more information, see Scylla Sphinx Theme.