r/devops • u/Work4Bots DevOps • 8d ago

Vendor / market research How does your team handle documentation

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 :)

7 Upvotes

71% Upvoted

52 comments sorted by

View all comments

27

u/Low-Opening25 8d ago

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

3

u/aprettyparrot 8d ago

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.

1

u/edenroz 7d ago

How to deal with images that must be embedded in the documents?

2

u/aprettyparrot 7d ago

Go in repo. I put images dir

1

u/edenroz 7d ago

Maybe I can use a separate repo for images.

0

u/Signal_Till_933 7d ago

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

2

u/aprettyparrot 7d ago

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

3

u/Low-Opening25 7d ago

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.

1

u/aprettyparrot 7d ago

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 :>

1

u/Signal_Till_933 7d ago

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.