In this blog post our team shares their experience and design choices in building our documentation site from scratch using tools like Gatsby, Markdown, Docz, and MDX. Read on if you want to learn how to build beautiful, maintainable docs for yourself, and feel free to give us feedback at docfeedback@cyral.com.
At Cyral we’re all about simplicity. Cyral was designed as an API-first product that makes security easy for engineering teams to operationalize and easy for all teams to manage through API calls. This drive for simplicity framed our choice of documentation tools, too.
With engineers as our main users, our docs face two challenges:
- Provide quick answers. DevOps teams move quickly. Our docs should provide answers almost as fast as a competent colleague would, maybe faster.
- Always be up to date. Our docs must keep up with our fast-growing product and an ecosystem that changes just as fast.
Let’s look at how we’re addressing these needs in the Cyral documentation.
Quick with the right answer
To get the reader to the answer fast, our product docs needed to have certain traits:
- Accessible and searchable: Not behind a firewall, and not buried in a PDF. Searchable from the web, and searchable within the scope of the site.
- Tightly integrated: In an API-first product, the API docs need to be coupled with the deployment and UI documentation seamlessly.
- To the point: For a DevOps engineer, Cyral is one tool in a large set of tools. On visiting our documentation, they should get the one answer they need for proper integration with Cyral. Deeper discussions are available through links.
- Flat: We keep explanations as self-contained as possible. Most readers arrive with one problem to solve. So wherever possible, each page of the documentation should answer the question that brought the reader there, and not force them to wade through anything else.
- Readable: Dense, head-to-read text is usually a sign of another problem, like the need for a product usability fix or a separate page of documentation. We weed out these sections and fix the actual problem.
- Concrete: Wherever possible, we illustrate each point with an example.
The list above lays out our editorial goals, but we knew that the only way to keep meeting those goals over time was to have a nimble architecture that encourages frequent updates and constant, quick-turn content review cycles.
As anyone in DevOps knows, it’s over the long term, when you’re maintaining a system or keeping a service available day-to-day that you see the payoff from good design choices you made. In building a documentation system, those design choices can make the difference between a documentation site that goes stale in a month and one that stays fresh because it’s easy to update in the course of everyday product development.
Smash the barriers that delay doc updates
Ensuring that documentation is always up to date means eliminating the barriers to creating, updating, and reviewing documentation. The biggest potential barriers to be removed are:
- Limited availability of people who can update the documentation. We couldn’t bottleneck the development process on a single writer. That meant choosing documentation tools that everyone on the development team can use.
- Limited availability of tools to review, write, and fix the documentation. If we really want every developer and writer to be able to work on the docs, then we can’t force them to install unusual tools or, even worse, ask their manager for an expensive license for an editing tool they’ll use only once a month.
Removing those barriers meant:
- Optimizing for ease of content contribution: Everyone on the team should be able to write, edit, and review.
- Optimizing for customizability: Our tech stack should be highly extensible.
Let’s look at each of those in turn.
Optimizing for ease of content contribution
Anyone on the team should be able to contribute to and improve our documentation content. Simple markup standards like Markdown are great for this, and (spoiler alert) we decided early on that our documentation platform would have to support Markdown so that everyone could contribute, just by editing text files in the editing tools they use every day.
Markdown was an easy choice: We already had customer-facing instructions written in the language, and it’s simple for anyone in the organization to create new documents that can later be harvested for our customer documentation. With Markdown, there are no proprietary tools that become barriers to entry: everyone can contribute, and everyone can help maintain.
Our site deployment is backed by git version control, meaning that contributions are made by committing changes to a code repository, in our case, one residing in GitHub. As a result, not only is our documentation version controlled, but we’ve established a collaborative change review process based on the pull request mechanism.
Git and the use of pull requests are well established as a foundation for collaborative software development, and the addition of a simple web interface in tools like GitHub and Bitbucket has opened up this mode of collaboration to everyone—command line mastery is no longer a prerequisite! As a result, in recent years git backed by platforms like GitHub has become the basis for many kinds of collaboration, including everything from pizza dough recipes to security policies. In our case, this means that anyone on the team can add to the documentation, see what’s changed, provide review comments, and make corrections almost instantly.
Optimizing for customizability
We chose to build our documentation using Gatsby, a popular static site generator with a vast ecosystem of community-backed extensions and tooling. This ecosystem served as a springboard for our development—we used a Gatsby theme called Docz as a starting point for our site. Because it’s open source, we were able to fork and customize it to our liking.
What’s more, Gatsby can be used with MDX, an extension to Markdown that lets you include JSX in Markdown documents. This opens up a world of possibilities, allowing us to easily build features which promote usability, like tabbed sections, copyable codeblocks, and an interactive API reference.
For example, a tabbed section like this:
requires just a simple block of MDX:
<Tabs
defaultValue='terraform'
values={[
{ label: 'Terraform', value: 'terraform' },
{ label: 'Cloudformation', value: 'cloudformation' },
]}
>
<TabItem value='terraform'>
Use the ELK Terraform template...
</TabItem>
<TabItem value='cloudformation'>
...
</TabItem>
</Tabs>It’s worth noting that we also considered using Docusaurus, which had more features out of the box but was ultimately less customizable than Gatsby. Nonetheless, Docusaurus is a great tool, and in fact we use it for our open source project Approzium.
Simple and up to date, all the time
The combination of easy content contribution and a customizable publishing pipeline has helped us create a documentation site we’re happy with, and more importantly, one we can keep up to date with a minimum of work. The engineering team was on board from day one, since many engineers were already using Markdown as their default documentation tool. For the wider team and for those using other formats, the learning curve was short, and when we need to convert a Confluence article or Google Doc to Markdown, it takes only a few minutes.
Finally, we’re happy with the decision to build on Gatsby and MDX given their broad acceptance and use of the popular JSX. This lets us avoid using proprietary or custom-built tools for formatting our docs, ensuring longevity since more of the team can work on not just the doc content, but on how the published docs look and function on our site.
