Docs-as-code at Talon.One

Integration - connector code

Development

Sep 14, 2022

Arthur Flageul, documentation lead talon.one

Arthur Flageul

Documentation Lead

Time to read icon

6 minutes to read

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.

Replicating the process

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:

talon.one docs as code pipeline illustration

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.

Replicating the tooling

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

Coding phase

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.

Testing phase

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:

  • Markdown can be linted, just like any coding language.

  • English can also be tested to ensure the style guide is applied using Vale.

  • The output can be tested too, for example, to detect broken links or accessibility issues.

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.

Review phase

The review phase is typically a 2-step process:

  • The subject matter experts validate the content.

  • Another technical writer checks the content for efficiency and clarity.

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

Deployment phase

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.

Monthly Newsletter

Every month, I share an insights newsletter with thousands of marketers.

bullet point check

Promotion tips

bullet point check

Industry insights

bullet point check

Case Studies

Newsletter author

David Hartery

Content Lead at Talon.One

Talon.One Logo
The World's Most Powerful Promotion Engine
BERLIN

Wiener Strasse 10
10999 Berlin
Germany

BIRMINGHAM

41 Church Street
B3 2RT Birmingham
United Kingdom

BOSTON

One Boston Place, Suite 2600
02108 Boston, MA
United States

SINGAPORE

1 Scotts Road, #21-10 Shaw Centre
228208 Singapore
Singapore

Capterra LogoMach Alliance LogoMach Alliance Logo
© 2022 Talon.One GmbH. All rights reserved