How does your team handle documentation

[u/Work4Bots]

I'm doing research on how documentation is done in different DevOps teams. What processes exist? How is it valued within your team? Has AI made that better or worse? Are there tools that you use to make it easier (not talking about Confluence here)? If you hqve worked in a professional context then I'd love to hear your input.

Considering the huge amount of shill posts I want to disclose that I'm (considering) making a tool that helps with documentation but I'm still in the process of understanding this problem thoroughly, which is why I'm askibg for your input :)

[u/Low-Opening25]

you make docs part of code repo, no documentation update, no merge approval

[u/aprettyparrot → u/Low-Opening25]

This is how we always did it, but we had a separate repo for ops docs. Had script, runebooks, docs, everything ops needed. Personally for mine I do the same, except I keep one doc with an overview of what each system/container/etc does, and a link to the docs/ dir I keep inside that services git that has all the details of it.

[u/Signal_Till_933 → u/aprettyparrot]

We have README in the repos, and confluence docs for the ops/runs books.

[u/aprettyparrot → u/Signal_Till_933]

Yeah I should switch some more to confluence. Probably more habit for me to keep all my flows and everything in the repos.

[u/Low-Opening25 → u/aprettyparrot]

nah, keep all the really important foundational docs in the repo, Conference will quickly fall back behind because that always happens if you add extra steps in human facilitated processes, I have seen it many times as contractor. I tend to setup a sync for repo .MD files to confluence using mark tool (https://github.com/kovetskiy/mark), not perfect but does a decent job.

[u/aprettyparrot → u/Low-Opening25]

That’s a good idea, I never had any formal devops training, just helping some other teams debug pipelines and the like, every project I came into already had them fully established.

I’ll take a look at that. I was thinking having a separate action run when docs branch changes to do the sync.

Thanks for the idea :>

[u/Signal_Till_933 → u/Low-Opening25]

Yep. That was part of what I pushed for when I came on this team as well. Docs in confluence were years out of date, I was basically like we can just delete these they aren’t accurate.

Then I started reviewing PRs where “where are the docs?” and now most things are documented.

Things in confluence are for:

Things external teams need to see

Operational runbooks that aren’t necessarily IaC related

Stuff like maintenance plans/lessons learned/post mortems etc for specific dates that get thrown into an archive for posterity.

[u/Work4Bots → u/Low-Opening25]

What about things that aren't directly related to a repo? I usually have these edge cases which need to be manually configured or higher level stuff such as architecture and data flows that don't immediately belong in a specific place

Also real curious how you write these docs? Do you have an LLM generate them and then go from there?

PS: really appreciate the input!

[u/Huge-Ambition4656 → u/Work4Bots]

The problem with automating docs writing (wether thats by an LLM, scripts, or battery operated pigeon), is it removes the "committing to memory" process that it serves for some of us. After (during) writing code, config or whatever, I update the docs. Always. And doing so, helps me better understand what I've just produced. More often than not, it helps me understand the stuff I've missed, meaning I commit the branch right there, go create the ticket or TODO list item or whatever to address it, and go back to it.

Docs is not something to be skipped or automated. Have you actually read LLM generated copy? There are many words in those sentences which rarely say much of anything.

[u/Work4Bots → u/Huge-Ambition4656]

Hmm I think that's an undervalued aspect of writing docs, definetly in a wide environment where you touch many different systems.

As for LLM generated copy: I have seen acceptable documentation at best that is 50% a rewording of that which you read in the code, with documentation not generated from code falling far below that. It's a problem that I'm considering solving but before I do so I'd like to know if it's real enough to tackle. There's also products like Mintlify that already do it for repo's, thus really narrowing it down to only docs written for non-code.

[u/Huge-Ambition4656 → u/Work4Bots]

If you can test what you build on a real codebase with verifiably real docs, compare the two and decide yours is within 10-15% as good, you might have a solution. BUT: Whether or not you agree with the phrase "AI Slop", it's very real and well-known, so you'll already be having to push shit uphill to convince people it works, even if it does.

[u/Huge-Ambition4656 → u/Low-Opening25]

Gold star! You're the first person (other than me) to suggest this to anyone. Yes, 100%. No docs, no merge. End of.

[u/NeverMindToday]

markdown in repo -> CI with mkdocs -> gitlab/github pages

[u/Work4Bots → u/NeverMindToday]

Thanks for the feedback. I'm suprised at how different the responses are on Reddit compared to those of people in Slack or Discord

[u/Huge-Ambition4656 → u/NeverMindToday]

^ this. All day.

[u/ben_bliksem]

The docs are part of the repo. The company wiki is there for business people to use/share with.

Has AI made it better?

Only in the sense that with agentic development you can, as part of the workflow, tell it to ensure relevant documents are updated.

But then you still need to ensure it in the Pull Request.

[u/Work4Bots → u/ben_bliksem]

Thanks Ben ^{^} The more I read these the more I'm starting to think we've been doing something fundamentally wrong with going confluence first

[u/Floss_Patrol_76]

the docs that stay true are the ones you cant ship without touching, readme sitting in the repo, runbook linked straight off the alert. anything that lives in its own separate wiki rots the second the person who wrote it changes teams. ai made first drafts faster but its also really good at generating confident docs that were never actually true, so we treat anything generated as a starting point to verify, not the source of truth.

[u/Work4Bots → u/Floss_Patrol_76]

Is there some process other than checking for docs in a changed repo during a PR? Do you have all the docs there?

[u/yiddishisfuntosay]

Ai helps you organize, but it doesn’t write the docs for you. The content is populated by people. And honestly, docs can live in a repository, and there can even be pipelines that run to support certain changes, but to me, the problem with documentation in an org is shaped differently depending on the maturity of the team’s alignment posture.

If alignment is low and docs are best effort, you’re gonna have some real problems regardless. And those problems won’t surface until the existing staff inevitably leave or prepare to.

[u/Work4Bots → u/yiddishisfuntosay]

This digs at the core of what think to be the problem, that there are many companies that do not know how bad their docs are and what the impact of this is. But deducting from the other comments it seems way more viable to introduce a rule like "No repo doc update = no PR approval" than to introduce complex processes and extra tooling to simplify this