Introducing the Scalar Product Documentation Sites
At Scalar, we recently launched our product documentation sites for each of our products. For links to each documentation site, visit Scalar Documentation.
This blog post describes what our goals were, how we developed and host our product documentation sites, some features we implemented, and what other features we want to implement in the future.
Overview
Our goal was to develop documentation sites with search and navigation experiences that were separated by product. Having this separation is important because we want to show users documentation that is specific to the product they are using.
When designing the documentation sites, we wanted to ensure that each product documentation site had a similar look and feel to our website and other branded content. In addition, we wanted to make sure that we could provide documentation for each version of our products.
How we developed and host our product documentation sites
To achieve a set of product documentation sites that were different in content but provided the same user experience, we decided to set up separate documentation-only repositories for each Scalar product. We decided to use Jekyll as our static site generator, heavily customize a theme to match the Scalar brand, and add functions like versioned docs. To tailor the theme to match Scalar’s brand and add functions, we applied our knowledge of HTML, CSS, Markdown, Liquid, and YAML.
For hosting the product docs sites, we use GitHub Pages, which supports Jekyll natively. This aspect was important because we wanted to publish our product documentation sites quickly. GitHub Pages is sufficient for our current needs, but we need to keep in mind other options as our needs grow and we continue to improve the documentation experience.
Documentation sites for each Scalar product
As previously mentioned, we created documentation-only git repositories for each Scalar product. From those repositories, we deploy each Jekyll-based documentation site with its own product-branded subdomain.
Each documentation site includes the original documentation from source code repositories and is organized into separate repositories for each product. For example, the docs-scalardb repository is dedicated to ScalarDB Enterprise documentation and the docs-scalardl repository is dedicated to ScalarDL product documentation.
By separating the documentation sites by product, we can streamline the information retrieval process — through search and side navigation — to provide an optimized documentation experience.
ScalarDB documentation for enterprise customers and the open-source community
In addition to having product documentation sites for each of our products, we also have two documentation sites for ScalarDB:
- ScalarDB Enterprise, which requires a commercial license or a subscription to a pay-as-you-go model
- ScalarDB Community, which is our free, open-source product
For ScalarDB Enterprise, we have a comprehensive set of documentation that covers the robust features and various deployment methods for paying customers. For ScalarDB Community, we have documentation that applies to the features available for the open-source version of our product.
Separating the documentation for both product types ensures that users of the open-source version of ScalarDB are shown content that is relevant to them.
By separating the documentation sites by product, we can streamline the information retrieval process — through search and side navigation — to provide an optimized documentation experience.
Documentation navigable by product version
A notable aspect of our architecture is the versioning function.
In the documentation repositories, we devised a straightforward method of using folders to store versions of documentation. Unlike some approaches that rely on branches and/or plugins, this method simplifies updating versions of documentation while providing a seamless version selection experience for users.
Furthermore, we have the flexibility to specify the scope of search results, ensuring that users see documentation for only the most recent product version. This minimizes confusion, compared to showing search results for all product versions. An alternative method, which may be possible to implement in the future, would be to develop a function to allow users to select a specific version when performing a search.
Wrap-up
Now that we’ve launched the Scalar product documentation sites and implemented processes to ensure the content on those sites are updated regularly, we need to continue improving the documentation experience.
Some features we plan to implement in the future include:
- Expandable and collapsible sections in the side navigation
- Light and dark mode
- Copy button for code blocks
In addition, we’ve started working on a comprehensive reorganizing and revising of our documentation to help users get the most out of our products.
