Move IOOS Docs on ioos.github.io to a monorepo format?

[MathewBiddle]

This is merely a place to start the conversation and evaluate if the idea has legs.

Proposal Move all of the jekyll based documentation websites linked to from https://ioos.github.io/ to one mono repository.

Current State We have the below list of documentation sites that are built using the GitHub IOOS jekyll skeleton, which the theme is managed (via submodule) in the theme repository (main and navbars). Each of these pages have their own repository which contains all the docs and configs for each page. We have established a GitHub Action which (theoretically - explained below) keeps the pages themes in sync with our main theme (sync_theme.yml). So, the look and feel (and header menu!) is consistent across all sites.

• https://ioos.github.io/ioos-metadata/
• https://ioos.github.io/glider-dac/
• https://ioos.github.io/ioos-atn-data/
• https://ioos.github.io/mbon-docs/
• https://ioos.github.io/ncei-archiving-cookbook/
• https://ioos.github.io/conventions-for-observing-asset-identifiers/
• https://ioos.github.io/erddap-gold-standard/

Reason for proposal

One reason for this proposal is the fact that if a repository hasn't been contributed to for at least 60 days, the scheduled workflow (in this case sync_theme.yml) is disabled (see screenshot below). So, now repositories that haven't been updated in 60 days need someone(?) to go in and enable the workflow to keep the theme up-to-date. What repositories need to be updated? Who does this?

Potential solution If we move all the documentation pages to one repository, it will be less likely that we will run into this workflow being disabled. This also limits the technical overhead of managing submodules and themes in different places.

Some concerns from @MathewBiddle If we combine all the documentation pages into one repository and we want external contributors to review/edit/contribute, do we want to flood them with potential issues that are in no way related to a specific activity. For example, we put glider docs and hf radar docs under one repo. Folks interested in gliders would be monitoring a repo that has irrelevant conversations about hf radar. With the way we have it organized now, it's a little more clear about what repo a contributor might want to follow/contribute to by the way we've separated things.

We have also built a lot of community around some of the repos that have docs, that needs to be respected and clearly planned for if a transition is warranted.

Closing thoughts I'm not sure what the right approach is, but lets use this issue as a place to talk it through.

[MathewBiddle]

cc @mwengren @ocefpaf @kbailey-noaa @laurabrenskelle

Add others as you see fit.

[ocefpaf]

I'm not sure what the right approach is, but lets use this issue as a place to talk it through.

I guess that the safe approach would be to port all those pages into a temporary (draft) repo somewhere, and then transfer it to IOOS to publish the pages. We want to keep the same URLs to avoid user disruption. We can try to preserve the history of the repos, like what we did for the ngdac migration, but I'm not sure it is worth the effort. Maybe just adding the links to the original repos in a README is enough.

We have also built a lot of community around some of the repos that have docs, that needs to be respected and clearly planned for if a transition is warranted.

It will rock the boat for sure. However, if we do it "right," we can get a more active community that will exchange info across pages and/or the tech used to build the page. An hypothetical example: We just when through the process of adding mermaid diagrams for a particular page. If that have happened in the monorepo, others watching it would already know how to do it if they ever need (or at least it would be easier to find it).

Note that all GitHub Actions and pre-commits will benefit from this. They'll need to be updated, modified and run in one place.

Codewise (editing the docs text), it will be relatively OK b/c each repo will be in a subfolder and we won't edit them all all the time, causing conflicts, etc. We will only edit them all when automated checks run, but those would be far and few between.

[ocefpaf]

If folks are interested, here is a lighting talk+slides goind through the process of migration from multiple repos to a monorepo. They did that for code, which is much harder than docs!

[MathewBiddle]

There is a keepalive workflow https://github.com/ioos/ioos-metadata/blob/df9c850908218739aeae326f5aa6c906769e3206/.github/workflows/sync_theme.yml#L42-L49