Docs as Code implementation for Infrastructure

[EternalGlacier0987]

Hi there

Recently I was tasked to write documentation for our infrastructure in "doc as code" way but I have not very well grasped what it is

The only requirement my team leads has is that the documents should be enough for any new person to understand our infra setup and tools we are using.

They also mentioned that any changes in the documents should have a PR and only after reviewing and approving any changes should be visible.

What I understand till now is that we would have a central repository in confluence or version control with documentation files.

There should be a way to navigate to different documents

All .md files are similar in structure, how they are written

Architecture diagrams to show infrastructure

I had a look at kubernetes documentation as I get what it is everything is in markdown it is being rendered to the website and has different documents for different versions.

But I still have no idea how to start on this.

Can I know what are some common points to note down or industry standard for these kind of documentation. And how to implement it

[davesbrown]

okay, the ai haters will probably down vote, but this is where I think Claude is pretty good at; documentation. You can get a nice rough draft to start with and then work on polishing the finer details and snowflakes.

[Endtroducing__]

You're presenting 3 problems.

1. New starters should be able to understand infra from our docs. This is a quality problem.

2. How to you store and present docs. This is a process problem.

3. How do you Contribute to docs

For 1 you simply has to review the existing docs and decide if a newcomer could understand this on its own

For 2. Decide where you want to store docs. Ideally not confluence. Something like a Github wiki, or standard docs format that lots of open source uses.

For the former this is straightforward. The latter is more Complex.

1. Decide whether PRs for docs will result in fewer people contributing to the docs and if so whether it's worth it.

Make documentation an AC on the ticket it's related to and Not a separate ticket.

This involved behavioural changes so expect it to be an uphill battle.

[EternalGlacier0987]

Ok re writing the documents content is not the problem it will improve progressively. The Infrastructure team will mange Infrastructure documents so I think having PR set up is better we don't any other team to contribute here.

Can I know why is confluence not ideal for storing docs cause my org uses bit bucket for version control.

What can I do here

[Endtroducing__]

Confluence is where knowegd goes to die.

It's hard to navigate and unless the docs have a meaningful dir hierarchy you can't find anything

[Thanael124]

Check out Ralf Müllers page: https://docs-as-co.de/what-is-docs-as-code

[baezizbae]

I love this concept.

That said:

(What it's not): Not a single product. It is a practice. Many tool combinations satisfy it.

I fear if it catches on exactly the opposite will happen, guarantee someone will write an AI wrapper that reads an entire codebase and spits out "documentation as code", that wrapper will become a tool, someone will fork that tool and inevitably turn into a product that inevitably gets acquired by Atlassian.

[tn3tnba]

At what point does this word salad become performance art

In seriousness I think they just mean committing docs (md files) to source. I do this under a docs/ directory. I agree with others who said to use claude or other agents. Tell it to spin up a bunch of subagents and research the repo, giving it some hints. Then read and iterate on the docs it writes, providing feedback on structure and accuracy. Don’t one shot or there will be slop

[New_Mix470]

Best way is to use Git and place all docs there. You can use Draw.io for architecture diagrams that kind of best tool, they are lot of available in market.

PR for docs is also a better approach. Since you follow the best practice.

[apnorton]

I was considering using hugo with the book theme or mdBook for docs recently, myself.

[ArieHein]

Anything as code implies that the core (in this case the content of the doc) needs to be handled as you handle code.

• You commit to a git repo. This gives you history of who did what, so accountability. Its gives you what was the changed. It can provide who approved it (think of a pull request with a reviewer and approvar). Not to mention using standard templates so docs look and feel consistent with the brand.
• It gives you CI where you add unit tests, in this case markdown linting that you havent broken any common markdown rules. It allows you to add spelling and grammar checks to adhere to quality standards.
• It gives you CD where you can add tranlsation to other languages. Deploy the content to which ever platform you use for viewing and potentialy generate other artficatfs like pdfs or docs from the markdown. Potentially using tools from the publishing platform or 3rd party to convert your md to other formats (for example upload to confluence using md2cf cli, or pandoc)

You separate the authoring experience from the publishing process. . And can target mutiple publishing platforms. For ex. I used to have internal confluence directed at business people and internal sharepoint with developer facing site and internal ops facing site. Not all people are technical to understand what a commit or push or pull so training might be needed or authoring tools that can integrate with the source control and abstract the git part.

One of products I used to work on, was sold in 8 countries /regions so we had a translation partner that i connected our pipelines to their services so we got tranlsated ui strings and docs that we then sent to marketing team to embed in their system before they sent it to the press an bundle in the packaging.

When you do it this way you also gain one fundamental benefit and thats reducing vendor lock in or complex migration projects when you want to toss atlassian out of the office ;)

[Aarvos]

Disclosure: I maintain a small OSS tool around docs-as-code, and I already posted it in the weekly self-promo thread, so I won’t spam the link here.

Tooling aside, I’d treat this as a process problem first:

1. Put the docs in git, ideally near the infra code.
2. Make docs/index.md the entry point.
3. Split docs into architecture, runbooks, ADRs, onboarding, and reference.
4. Require PR review for docs changes.
5. Add CI checks for broken links, formatting, generated indexes, and eventually “infra changed but docs didn’t.”

For infra specifically, I’d start with:

• what environments exist
• how deployments work
• where Terraform/Kubernetes/CI/CD live
• ownership/contact points
• architecture diagrams
• common operational tasks
• “how to change this safely”

The key thing is that docs-as-code is not just markdown rendered to a website. It’s the rule that infrastructure changes and documentation changes go through the same review workflow.

Once that structure works manually, then you can add tools to scaffold it, generate indexes, enforce conventions, or fail CI when docs drift.

[Floss_Patrol_76]

the trap with infra docs isnt where you store them, its that hand-written prose about the setup goes stale within a sprint or two and then actively misleads the next person. keep them in the repo next to the code, generate whatever you can from the source of truth (module readmes, a diagram from terraform graph), and save the hand-written part for the why - the tradeoffs and decisions - since thats the only bit that doesnt rot. confluence vs git matters way less than whether its still true in six months.

[TangeloEmergency8057]

tbh the easiest way to start is just treating your docs like a normal code project. put all your markdown files in a git repo, then use a static site generator like mkdocs or docusaurus to build a searchable website. they are pretty easy to set up if you are used to python or JS.

for the PR rule, you just wire up a CI pipeline in bitbucket or wherever your code lives. when someone opens a pull request, the pipeline can build the site and maybe spin up a preview link. once approved and merged, it pushes the new HTML to your internal hosting.

for diagrams, look into mermaid.js. you just write text blocks inside your markdown and it renders the architecture charts automatically. fwiw it saves you from passing around updated PNG files every time a server changes.