Documentation and Code should be in the same repository

[kaitimmer]

Opencost should have docs and code in the same repository. This would help improve the docs mid- and long-term.

Right now, whenever I make a code change, I have to check out a second repo, open a second PR, and ensure they are merged/released simultaneously.

Describe the solution you'd like

It would be a lot easier and more convenient to have docs and code together in the same repo.

Therefore I think everything currently in https://github.com/opencost/opencost-website/tree/main/docs should be moved into this repository under /docs and released to the website with every new release.

Describe alternatives you've considered

The current way of doing things is an alternative, but for the reasons I mentioned, it is not so great. So I would like to discuss this solution and would like to hear why you decided on the current approach.

[dwbrown2]

Thanks for starting this thread! Any (CNCF) projects that you feel do this well? I feel like most projects I've seen like Prometheus have them separate.

[mattray]

The docs had been here in opencost/opencost, but we moved them over to opencost/opencost-website because it was easier to manage formatting and templating for inclusion in opencost.io. I think it's unlikely we'll move the docs back, unless we did some sort of git submodule (ick) on the opencost-website side.

The advantage would be if we had some sort of docs per release auto-generation, but that feels like a lot of work. If there are examples of this available I'd consider it, but maintaining docs is already a challenge.

[kaitimmer]

@dwbrown2 You have me very surprised. I just checked a few of them (I didn't do that before I opened the issue), and all I checked had them separate.

This surprises me. In my experience, putting docs and code as close together as possible always worked better. But maybe the scale of things here is an issue. I could imagine a lot of merge conflicts when editing the same docs files.

@mattray I would just put the docs under docs.opencost.io and wouldn't care too much about the layout, to be honest. But that is my personal preference. That way you could link out from the opencost.io, and have the docs be a simple mkdocs release to a different folder. So both can work in parallel. No git-ickery needed :)