Docs as Code — is it Easy?

Hi everyone, my name is Alexander Machulin, and I’m the co-founder of Gramax.
I’d like to share my experience using the Docs as Code approach in both product and client development.
The key question — is it easy?

– No, it’s hard.

Jokes aside, let’s get serious.

Recently, we started attending meetups and conferences for technical writers and analysts, where the topic of Docs as Code is gaining more and more attention — its advantages, how to start learning Git basics, etc.

The topic is great and important, but there are a few points I’d like to discuss.

How we came to Docs as Code

It was 2021. We were developing analytical systems for Pharma and FMCG manufacturers, and our CTO Andrey decided to improve our documentation workflow.
He suggested keeping all the information in Git and created a simple static site generator. For about half a year, I worked with Markdown and GitLab without even knowing the term “Docs as Code,” but I definitely knew a few things:

• I didn’t want to think about Git commands — especially cherry-pick, revert, and others.

• Every merge conflict was painful because there wasn’t an intuitive UI for resolving them. I wrote in VSCode, but the most convenient conflict resolver was in GitLab.

• I didn’t understand Git errors. My typical reaction looked like this:

  Andrey, I absolutely don’t want to mess with these branches.
  It’s easier for me to copy all the articles to dropbox.paper and tell the team “let’s just write there.”

• The analytics and support teams, gritting their teeth, tried to use Docs as Code too — but silently suffered for all the same reasons.
  At first, I tried to convince everyone how “easy and convenient” it was to create and merge branches (what a hypocrite).
  Eventually, we considered committing directly to the master branch a success.

What’s required for Docs as Code to actually work

You can get used to anything — I got used to engineering best practices.
But the problems didn’t end there.
For Docs as Code to function properly in your company, you need to use and integrate five systems:

1. Markup language and editor.
   Let’s say we write in Markdown in VSCode. Simple — but still counts as one system.

2. Markdown preview.
   You really need this to spot markup issues.
   The problem: VSCode plugins aren’t integrated with your or any other static site generator.

3. GitLab or GitHub.
   I’m a simple man — I see a merge request, I go to GitLab.

4. Static site generator.
   You need to connect it to your Git repo and configure CI/CD so that site rebuilds happen automatically.
   Initially, we had no CI/CD, and people constantly forgot to click “update” on the knowledge base site — so content was often outdated.

5. Diagrams.
   We made professional diagrams in PlantUML, Draw.io, Mermaid — and dumped them as images into Git. Depressing.

Of course, all this worked poorly.
It was too complicated for normal people, and the mix of tools felt like a student’s course project.

A few important questions our analysts raised:

• How do we share links with external clients?
  We needed links that clients could access, but random internet users couldn’t.

• How do we know when something changes in the knowledge base?
  If someone updated content, they had to go to a messenger, email, or task tracker and manually notify everyone.

Why we started developing our own Docs as Code product

After long experience with the approach, I wanted to list its advantages — but for me, there were none.
We kept using it only because we believed in the idea — that it truly works, but only if combined with automation and a good user interface.

So, tired of my complaining, our team of leading engineers at ics-it worked days and nights in the lab to create a miracle.
And they did — we evolved our static site generator into a full-featured WYSIWYG interface for GitLab — Gramax.

Gramax doesn’t restrict you from using Markdown, IDEs, or Git commands in the console.
It simply makes both technical and non-technical workflows smooth and intuitive — for writers and readers alike.

Why I’m telling you this

We built a great app and solved our own problems.
Now you can solve yours with it too.
It’s completely free to use, and in the coming months, we’ll release the source code as open source.

Download the app and join us in promoting the Docs as Code approach and best engineering practices in product development —
join our chat and share your own challenges!