At Ripple, we use a home-grown tool called Dactyl to compile and build our technical content as part of our "docs as code" approach. Dactyl is a static site generator similar to Jekyll, Hugo, and others. We didn't set out to create another tool in a crowded field, but it grew organically with our needs and we've found several advantages of having the tool itself be developed in-house. At Ripple, we believe in the benefits of open-source, so we make Dactyl available to developers under the permissive MIT open source license on our GitHub.
The Basics
They say content comes first, and in Dactyl's case that is literally true. We started with technical documentation, written in Markdown, and needed a way to parse it and publish it to a website. Markdown is great: it's similar to plain text, so it's easy to get started with. There are lots of tools out there that can edit it, and it's widely used across different organizations.
For software documentation, which straddles a gulf between technically-minded software developers and language-focused technical writers, Markdown is a solid bridge format that both types of teams are comfortable editing. Collaboration between people of different roles is the key to great software documentation.
Content alone doesn't make for complete documentation, though. Users also need structure, navigation, formatting, and visual styles. These things make up the user experience for documentation, and a large part of a good user experience in documentation is predictability: everything should work consistently, the same way, across different documents.
Executing this with a website creates substantial busywork. When one page grows to two, you must update the old page to link to the new one. When five pages grow to six, all five old pages need to be updated to add the new page. This tedious work gets in the way of delivering new documentation that people care about.
That's why, at the very beginning, Dactyl was just an unassuming 100-line script for automating this kind of process: parsing the documentation content, and putting it into templates that only had to be updated once.
Today, that's still the core of Dactyl. It takes us from plain text Markdown to nicely-formatted websites such as xrpl.org with automatic tables of contents, consistent headers and footers and more. This is just the beginning for a static site generator. Dactyl has been evolving alongside Ripple and XRP Ledger documentation since its creation 5 years ago.
Features, Features, Features
Over the years, we've added robust features to solve new challenges as we encountered them. Below is an overview of some of the exciting solutions Dactyl brings to the table nowadays:
- Link Checking. Broken links and 404 errors are an awful experience, but it becomes quite a challenge to find them all when you have hundreds of pages of documentation with hyperlinks peppered throughout. The link checker built into Dactyl finds and reports on broken links so we can catch them before publishing, or respond quickly when an old link dies.
- Single-sourcing so documents, guides, and code samples can be reused for related products and guides. Similar to how software works by writing code once and importing it where necessary, single-sourcing lets us write useful snippets of text one time and use them over and over. When those snippets need updates, one change automatically propagates to everything that relies on them. For content that doesn’t work exactly the same way in all contexts, Dactyl's single-sourcing pre-processor also supports syntax for conditional formatting and other procedurally-generated content.
- PDF export. Some of Ripple's customers need access to documentation from sensitive areas of financial institutions where internet access is carefully controlled. The ability to print a paper copy to carry into those areas is a crucial feature for Ripple's enterprise solution, RippleNet. Most of the heavy lifting for the PDF export is handled by Prince, but this is a special case of single-sourcing: Dactyl uses specialized templates for more elegant, usable PDFs that don't look like someone just printed a webpage.
- A plugin architecture for post-processing. This allows us to offer features beyond what Markdown natively supports, such as tabbed code samples, status badges, and specially stylized callout blocks.
- Multi-format export. In addition to HTML and PDF, Dactyl is capable of exporting to more "standard" GitHub-flavored Markdown (after applying the single-sourcing rules) as well as a JSON format specially designed for uploading to ElasticSearch, to power our enterprise documentation search.
- Style Checking. English is a hard language to master, but technical writing isn't meant to be artistic and flowery. Technical writing is meant to be easy to understand. Dactyl comes with a default list of recommendations, inspired by PlainLanguage.gov to replace words and phrases with simpler alternatives. It can't catch everything, but it's a good starting point for encouraging concise writing in plain English.
- Live Changes. Run Dactyl in the background and it automatically rebuilds your local instance of the site whenever you make changes.
Conclusion
At Ripple, we see our mission—to make money move as easily information—as neither a sprint nor a marathon, but an odyssey: a years-long journey, with twists and turns, ups and downs. With this in mind, Dactyl's name is inspired by the meter of ancient heroic verse.
Just as a dactyl is just one foot in an epic poem, Dactyl is just one step in creating epic documentation. As a team, we've come pretty far on this journey, but there is still more to accomplish. We hope you'll join us in making the future a better place, one step at a time.
