Where should docker-related documentation go?

[oliverbarnes]

Currently we have both https://docs.decidim.org/en/develop/docker/ and this repo's README (latest update is pending review on PR #78) , as well as the discussion on user stories that could also become documentation.

This issue illustrates how a dev trying Decidim out with docker might expect to use the docs for certain workflows.

I see a couple of options:

• https://docs.decidim.org/ docker docs could be extended, perhaps importing docs from here (decidim/docker repo)

• or the current doc page could point here (decidim/docker repo), and docs here could be organized in the repo's wiki.

The benefit of the first option is of course having a single go-to place for all Decidim documentation. But that also means perhaps having a very long documentation page there, or several pages worth, documenting the different usage scenarios of docker with decidim. With some overlap with the README here, too, which can be a little confusing - I think some devs don't even know decidim/docker exists.

I'm on the fence regarding this one, and would like to hear what you all think.

Seems like an offshoot of the monorepo/separate repo conundrum, too. For both I also see benefits and drawbacks, in this case 😅

** Update **

decidim/decidim#7311 updates the docs according to the discussion here, switching to documenting the deployment flow rather than the development one, favoring docker usage by instance implementors.

[andreslucena]

I'd also add the Docker Hub page that as far as I remember it's updated manually from Docker Hub panel 😓

For me it's better to have everything published at docs.decidim.org that's relevant to implementers and the README pointing there also.

perhaps importing docs from here (decidim/docker repo)

That's overkill at the moment, although if we see that's necessary we could do it in the future (I've done this in decidim/decidim already). It's a pain specially because the navigation in antora is defined in the documentation repo and if you add any new page in this repo then you also need to add it there.

docs here could be organized in the repo's wiki.

I'm not a fan of GitHub Wikis, I prefer to work everything in plain text, that allow us to not have that much vendor lock-in and also to have review and git tooling.

[oliverbarnes]

Ok, makes sense. So, if I'm understanding correctly, for now I'll change the docker docs on docs.decidim.org to have instructions on how to deploy a basic decidim instance with our decidim docker image?

The decidim framework development workflow currently documented there (the d/bundle, d/rails docker-compose wrappers) really does seem hopeless, unless I'm missing something big that would make it work. Here's my latest comment on it: decidim/decidim#7082 (comment)

If you agree, I'll remove this altogether, and just document the docker instance deployment flow.

[oliverbarnes]

About Docker Hub, thanks for pointing it out - I wasn't aware! Looks like that's because the automatic build is disabled. I've manually updated it now with the latest from the repo.

[oliverbarnes]

decidim/decidim#7311