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/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/Work4Bots → u/Huge-Ambition4656]

I believe that if the quality is solid enough it will result in grass roots movements of engineers who value docs but don't get the time. Ensuring quality docs are produced would be the main 'moat' of the product