In my first job as a technical writer, there was a problem. We didn’t generate two different types of deliverables (HTML and PDF) from the same source—a practice that, I learned, is called single-sourcing. Having this in place is considered table stakes for any decent technical documentation toolchain.
This is true now and was true ten years ago, when I had my first job, as the second technical writer at an email routing company. My mentor was the first technical writer, but they were overmatched by the technical complexity of the single-sourcing implementation. In the face of pressure to deliver docs on tight release deadlines, they resorted to a workaround instead of solving the root cause.
This was the workaround: as the source changed, they copied the text from an application called FrameMaker and pasted it into the pre-existing HTML tags in another application called RoboHelp. Solving the root cause would've streamlined the process: change the source, prompt RoboHelp to regenerate the HTML.
The workaround was painstaking, slow, and error prone. It also severely limited the team's velocity and the type of content that the team could produce. Every change required essentially double the time and effort (write new content, then copy and paste it in another syntax). And what if we added an image? Where would the HTML tags for that be? We couldn't even envision how to make a fundamental change, like updating the style or structure of the documentation. Developers were reluctant to help because the applications were closed, proprietary, and required a non-trivial amount of training to understand (not to mention the problem of licenses).
The single-sourcing implementation was a challenge. Especially for someone like me, who had little to no experience and didn’t know
cd ../ from
rm -rf *. Nonetheless, I took up the challenge. I was lucky: the company had enough resources to get developers and consultants who shepherded us through the project. It was a great learning experience. It was also an expensive one.
The complexity and expense were both largely due to the reliance on one closed, heavyweight application that is resistant to user modification. While any choice of tools or systems is inherently limiting, choosing a "help authoring tool" (HAT) application typically means you’re also choosing to deal with one company’s array of products and services for that product.
You're also choosing to limit the number of people who can contribute to the docs: traditional HATs tend to require application-specific expertise and tiered licensing. Changes can be slow, costly, and inflexible. These tools also create a distance between the writer and the content—and technology itself.
If you have an army of technical writers, then you probably want to choose a tool like this: easy-to-use, capable of producing easily replicable results, difficult to modify. If you’re a small startup with only a few writers, this type of tool may not be such a good choice.
Ripple is a different company than when I joined five years ago. I've made a lot of decisions in that time. I think about these choices often and have tried to learn from all of them. But choosing to use a home-grown static-site-generator has been an unqualified success. Using this tool, an open-source Python package called Dactyl, has allowed the team to scale and to expand its charter—by making it easy to reuse content, invite contributors from outside the team (developers, product managers, integration engineers, etc), and to modify styling and functionality. All you need is a terminal, a text editor, and a little familiarity with Git workflows.
We're overwhelmingly happy with what the approach has done for us. Here are a few examples of the benefits:
- We leverage Git-based tools for doc reviews, which make it easy to make in-line comments and even to provide suggested changes.
- Because the process and tools (Git, IDEs, lightweight text editors, etc) are familiar to them, developers are comfortable reviewing and contributing to our documentation.
- We can automate things like checking for broken links or publishing on merges. (We're working with a development team to automate the generation of API responses for different use cases.)
- We can publish to different target platforms and formats without retooling the content (much).
- By editing YAML and XML files for things like OpenAPI (Swagger) and Liquibase to auto-generate references, we get exposure to the application’s source code.
The tools and frameworks can be technical, complex, and sometimes unintuitive. But we rarely run into problems that we can’t solve through a little research, testing, experimentation, or collaboration.
In the next few weeks, members of the Ripple Docs team will dig deeper into these and other aspects of the Docs as Code approach. You can look forward to posts about topics like:
- Learning (to love) Git
- How to build your own static-site generator
- Leveraging GitLab pipelines
- How important it is to test software yourself
- And more!