Docs-as-code at Talon.One

At Talon.One, documentation is not an afterthought. We treat it as a normal development task, with a docs-as-code approach.

If you are a technical writer, you might be using docs-as-code, or perhaps you've heard of it. If you are a developer, you might be wondering what documentation and code have in common. 

The answer is a lot. 

Actually, they are so similar — you might even consider becoming a technical writer!

Documentation is often perceived as a strange, hybrid project. 

Just placing a Documentation team in a company's org chart is difficult: should it be part of the Product department? The published documentation is also a product in itself, after all. 

But perhaps it should be part of the Engineering department, to be closer to the development effort? Maybe so. 

Wherever you think the Documentation team should live, does it warrant having a specific workflow and tools?

At Talon.One, documentation is part of engineering. Whether we think about the overall process to track docs change or consider the tools we need to create content, we don't think it's any different than code. We do our best to replicate established processes from the development world... into the documentation world.

We use Agile to organize our work in the engineering department and when an epic is refined into smaller tasks, typically including backend and frontend tasks, we also create the required documentation tasks.

The rest of the process is also completely applicable to docs: refine your ticket, write the docs, send them for review, and publish when reviewed.

On a finer level, our development workflow relies a standard continuous delivery approach with the usual main steps:

The good news is that development teams around the world have been using and refining this process for years, and technical writers can confidently copy it. This process is so standard that many tools are readily available to help us apply this process.

Once again, there is no need to reinvent the wheel, let's just leverage development tools.

The coding phase obviously turns into a writing phase, and just like developers, a technical writer should only need a plain text file, relying on Markdown, rST or AsciiDocs for semantic tagging. Forget about Word, FrameMaker, and other proprietary software and binary files. Choose the text editor of your choice. Like many, we like VS Code.

The test phase is crucial in any workflow. A developer can write various types of tests to ensure the quality of their code is where it should be. The tests are automatically run, and errors are reported by the computer while the developer is enjoying a coffee. Technical writers can also enjoy a coffee as the computer works for them:

At Talon.One, most of these tests are managed via GitHub actions and git hooks, and they are rather quick to run, so we are talking about an espresso length of time, here.

The review phase is typically a 2-step process:

Naturally, we use GitHub pull requests for this, just like a code review.

Finally, when the pull request is approved, it can be merged and a GitHub action will rebuild the published output. In the case of Talon.One, our docs are a single-page application built with Docusaurus.

Hopefully, we demonstrated that docs can be treated as code, which brings the docs deeper in the development flow, meaning they become cheaper to keep up to date. We could also decide to open-source the documentation, or give write permission to every Talon.One employee to promote contributions and make the documentation even more of a joint-effort.

The potential downside is the amount of technical knowledge required to use this approach, and that technical writers might lack. At Talon.One, we do not need our tech writers to be mini DevOps or junior React developers to maintain the docs, but we need some degree of interest and motivation to learn to work with the command line.

In our experience, working in such an environment helps develop our writers' technical skills, In turn, this helps them interact more easily with developers, and deliver better technical documentation.

So, should you implement your own flavor of docs-as-code? We think you should!

Check out the Talon.One docs in full at docs.talon.one.