Why your Ansible repo has no documentation (and how to fix it without writing any)

Gary Sparks — Wed, 29 Apr 2026 13:20:01 +0000

I've been in platform engineering for four years. In that time I've worked with Ansible repos ranging from tidy and well-structured to the kind that make you question your career choices.

Almost none of them had documentation.

Not because the engineers were lazy. Not because nobody cared. But because writing infrastructure documentation is genuinely terrible work that sits at the intersection of two things engineers hate: context switching away from real work, and writing prose about things they already understand.

The result is a specific kind of organizational debt that's invisible until it isn't. New hire joins the team. Senior engineer gets pulled into three days of "can you explain what this role does." Someone leaves and takes three years of tribal knowledge with them. On-call engineer gets paged at 2am, opens a playbook they've never seen, and has to reverse-engineer what it does before they can fix anything.
Sound familiar?

The documentation conversation always goes the same way

You bring it up in a team meeting. Everyone agrees it's important. Someone gets assigned to write docs for their area. A week later nothing has happened because there are tickets to close and incidents to respond to and documentation is always the thing that gets pushed.
So you try making it a requirement. Docs before merge. Now engineers are writing one-line descriptions that tell you nothing: "This role installs nginx." Thanks.

The problem isn't discipline or process. The problem is that writing documentation is a separate cognitive task from writing infrastructure code, and nobody has the context and the time at the same moment.

What actually worked

I got tired of fighting this battle so I built something to fight it for me.

The idea was simple: the code already contains everything needed to generate the documentation. The role name, the variables, the tasks, the handlers, the dependencies. It's all there. What if an AI just read it and wrote the docs?
That's what Stacklore does. You connect your GitHub or GitLab repo and it reads your Ansible roles, Terraform modules, and CI/CD pipelines and generates structured documentation automatically. Every file gets a doc explaining what it does, what variables it needs, what it provisions, and what to watch out for.

The part I'm most proud of: when you push a commit, a webhook fires and the affected docs update automatically. The documentation stays current without anyone thinking about it.

Your team gets a private searchable portal where anyone can browse the docs or ask questions in plain English — "what variables does the vpc module need?" or "which roles touch the nginx config?" — and get an actual answer instead of having to grep through YAML.

The change nobody expected

The documentation itself wasn't the thing that changed how the team worked.

What changed was that junior engineers stopped interrupting senior engineers. Not because the senior engineers became unavailable, but because the answers were findable. The question "what does this role do?" had an answer that didn't require a 20-minute Slack thread.

Senior engineers got their focus back. New hires got up to speed faster. On-call handoffs stopped being a game of telephone.

The documentation was always the symptom. The actual problem was that knowledge lived in people's heads instead of somewhere searchable.

Try it

If your Ansible or Terraform repo looks like mine did, functional, well-maintained, and completely undocumented, Stacklore is free to try with one repo. No credit card, no setup beyond connecting your GitHub or GitLab account.

It won't make you write a single word of documentation.
Stacklore

DEV Community: Gary Sparks

Why your Ansible repo has no documentation (and how to fix it without writing any)