Pulling docs from their respective repos

[flaki]

This is potentially a way to improve on #106 !

I just noticed that we have some lingering documentation in the subo repo. Upon closer inspection the getting started docs page is more or less an equivalent (but less detailed) version of this document (and it's also linked on the subo docs page).

My first gut reaction was to remove the doc from the subo repo and move the extra information into the docs, this would certainly serve for better consistency, but as it was raised in #106 would also further exacerbate the subo documentation being disconnected from the code.

An idea that came to mind to work the other way, and make an e.g. docs folder within the subo repo the single-source-of-truth! That is, we could write the docs for subo in the subo repo, and would have Docusaurus pull these files in when it publishes the documentation. Similarly how I outlined in the current code snippets PR we could tag these imports to a given tagged version of the repo, which would ensure proper versioning.

I can imagine two ways of pulling these files in, both has its advantages and drawbacks:

1. Just use git submodules. Submodules are not the easiest part of git but would come with making this relationship very straightforward and pulling in the markdown files would be trivial. A drawback would be extra maintenance and, well, having to deal with multiple submodules from all over the place.
2. Use a similar mechanism that we have for the above linked PR for pulling in code snippets. Code snippets are fetched from GitHub and can be cached but are currently not. The drawbacks are clear: when GH is down or when the user does not have the files cached (e.g. working offline) the files are missing and the build may fail. The upside is that we could make updating and maintaining these a bit less of a hassle.

[javorszky]

I am very much in favour of keeping the documentation together with the thing being documented for two reasons:

• developers and new folks to the company will not need to search where the documentation for a thing is, as it's with whatever they're looking at. They can also assume that any documentation on whatever branch they are is up to date
• we can also enforce manually a "new / changed functionality must be accompanied by documentation changes". I am somewhat aware that developers / engineers aren't necessarily the best at writing final documentation, however I think we should still get into a flow where the folks responsible for writing code can also write documentation to make the devrel folks' lives easier

In previous places we had a bunch of webhooks and whatnot set up so when there was a push on a functionality repository, it would ping the docs repo and trigger a build that would pull in the current state of that documentation.