Automation in Documentation: Docs-as-Code vs WYSIWYG Editors

TL;DR

As technical writers, we spend countless hours performing repetitive, manual tasks that can be automated. But depending on your documentation platform, it’s either refreshingly simple or frustratingly impossible. This post explores what happens when you try to automate documentation tasks across docs-as-code and WYSIWYG systems, and what that says about the future of writing with intelligent tools.

In my post The Little Beginnings of an Automated Life, I wrote about my growing obsession with small automations, the kind that passively help you focus on things that actually matter, instead of getting lost in busy-work.

This time, I want to share some concrete examples from my experiments with various documentation platforms.

Problem statement

For a recent project, I needed to find and catalog all the videos embedded across a large documentation site built with Hugo. Sounds straightforward, right? It can be, if you’re using an IDE like VS Code or IntelliJ IDEA, which lets you search across your entire project using keywords or regular expressions.

However, if you’ve worked with Hugo, you probably also know that it supports shortcodes for embedding videos from YouTube, Vidyard, Vimeo, and others. Now, imagine trying to locate every one of those embeds with an IDE of your choice, while accounting for the project’s size and all the shortcode variations.

For example, to find Vidyard embeds, one might search for variations like:
{{% vidyard code %}}, {{< vidyard "code" >}}, {{< vidyard code >}}.

And that’s just for Vidyard. Add YouTube and Vimeo embeds, plus any locally hosted videos or direct link embeds, and multiply that across dozens of files. Suddenly, a quick search turns into a tedious slog.

So I did what I now almost instinctively do: I wrote a script.

Scripting the solution

The first version of the script did the bare minimum by only listing which files contained video embeds. Helpful, but not really what I needed. It felt like switching from sorting dried beans with bare hands to sorting with gloved hands, a little bit of finesse, but still the same stress.

So, I iterated on the script. The updated version produced a clean, readable table that listed each documentation page alongside its corresponding videos, complete with constructed URLs (such as https://www.youtube.com/watch?v=code for YouTube or similar formats for Vidyard), as well as a handful of other functional parameters.

This task, although it required some upfront effort, is one-time, replaced hours or an entire day of manual work, and will continue to deliver value for as long as we need this information. Now, anyone who needs this data won’t have to waste hours digging through files by hand or rewriting a script.

My next goal is to make the workflow entirely hands-off, automatically updating the table and sending alerts when new embeds appear or existing ones change. However, this is a future “nice to have” enhancement, and we’ll see if it actually happens.

However, as a technical writer with a truckload of curiosity and a constant need to experiment (mostly to stay sane), my success with the Hugo script led me to wonder about the feasibility of this kind of scripting or automation in other documentation solutions. So, on a beautiful weekend, I decided to find out.

I explored several platforms to see how their underlying structures either enabled or complicated automated content management. The biggest takeaway from that exploration was the stark contrast between “docs-as-code” and WYSIWYG (What You See Is What You Get) platforms.

I’ll share some of these insights below.

Docs-as-Code platforms

This didn’t require much effort and it was relatively easy to achieve my test case here, since most of these tools, like Hugo, follow the docs-as-code philosophy to some extent. They’re file-based, version-controlled systems, which means I am able to:

• Run searches across source files
• Use a command like grep or write custom scripts to extract data
• Automate as much as I'd like

The only real caveat comes when you rely on the web editors offered by platforms like Mintlify or GitBook. In those cases, your flexibility takes a hit, and the balance leans heavily toward what you can’t do (just because you’d like to).

For example, in Mintlify’s web editor, it’s convenient for quick edits and searching for file names, but not for media files, which happened to be my test case during this exploration.

Finally, the takeaway from this is that docs-as-code makes automation very much possible and easy. This possibility makes sense, and it is not surprising, because at its core, the whole idea of docs-as-code is about treating documentation like code.

But what about WYSIWYG solutions?

WYSIWYG editors

These tools, which are mostly all web-based platforms, are generally good. That said, while these platforms shine in their visual and user-friendly editing experience, this often comes at the cost of direct access to underlying files. And that limitation can get frustrating fast.

Here’s what I found during my explorations of two solutions, Nuclino and Document360:

Nuclino

Starting with Nuclino, despite the platform’s AI-augmented search (as most searches are these days), it fell short for my use case. To locate videos, there was no programmatic way to extract or search for embeds; instead, I had to manually open each document to check if it contained one, which was too much effort for too little return.

Document360

With Document360, things got a bit more interesting. The platform has its own drive; if you upload videos directly, you can easily locate them as local files.

However, the catch here is that, if your documentation structure mirrors your folder hierarchy, for example: platform > quickstart > hello_world > video.mp4, you’ll quickly run into trouble to find videos. You would need to dig through each nested folder manually, and with a large hierarchy, that becomes a nightmare.

It gets even trickier with embedded videos, since they can only be added via link or iframe embed, which means they don’t appear in the drive at all.

Other approaches I tried

After the above approach didn't pan out, I decided to try the provided Document360 APIs, hoping they'd offer a cleaner way to fetch media references.

• Using /v2/Drive/MediaFiles/:projectVersionId/:articleId/:langCode?appendSASToken=false, I was able to get data of all the files in the drive, but not the embedded content.
• Searching inside the platform? Well, the search bar is unable to locate images or videos within the content. You can tag files in the drive and search those tags, but again, that doesn't help with embeds.

What actually worked

Export + Search.

By exporting the entire knowledge base (media included), I was able to download everything locally and run my commands.

It’s clever, but also clunky. For large documentation sets, exporting can be time-consuming, and if you need to repeat the process, you’ll have to re-export every time.

At some point, I considered creating a custom JavaScript solution, but that felt like overengineering. Compared to my experiment with the docs-as-code solutions, this was just too much hassle.

Docs-as-Code vs WYSIWYG

In the end, this exploration reinforced a key insight that docs-as-code solutions deliver more flexibility for scripting and automation than WYSIWYG editors.

The ability to use the command line and scripts to manipulate documentation is such a huge advantage that WYSIWYG editors can’t match. While some WYSIWYG platforms offer their own forms of automation, they often come with the trade-off of vendor lock-in that can quickly turn into a blocker if you ever need to migrate away from the platform.

Final thoughts

Automation or merely the thought of the possibility if it should be a design principle. It should be baked into how technical writers and decision makers evaluate and adopt new documentation tools.

When assessing any platform, don’t just think about how easy it is to write with. Look a bit deeper, pay attention to emerging trends, and ask questions like:

• Can I scale my content management as the project grows?
• Can I extract and transform data without vendor lock-in?
• Does this solution have automation potential?

And for technical writers especially, when approaching your daily work, it’s worth asking:

• Where am I repeating myself?
• Where am I wasting time on something a machine could handle?

It may seem like “looking too much into the future,” but it’s an investment that will pay long-term dividends, both for you and your team.

Looking ahead: Intelligent tools and writer experience

More than anything, this exercise reminded me that while most platforms focus on the end-user experience, with the now too familiar “we want to provide the best possible experience for your readers” pitch, writers and editors also deserve some attention in that conversation.

We often discuss making documentation more intelligent for readers through search optimization, personalization, AI-powered suggestions and the like. However, as AI continues to integrate into writing and documentation workflows and humans approach the singularity, documentation solutions should also begin to consider writers as users. Users who deserve intelligent tools that help them automate, produce content smarter, faster, just maybe a little more sanely, and focus on higher-value work.