Consider simultaneously displaying "published" and "draft" versions

[itcarroll]

While we don't need to have a live URL to every release, as you would have for software documenation, I think it would make sense to have the landing page default to "stable" while also providing a link to a "latest" view. I'm not suggesting that "stable" always be the current release, since we don't want to tie what's shown on "stable" to what has been merged to main. Rather, all content is stable unless it is tagged as a "draft".

I think using public drafts would make it easier for authors to separate development into multiple PRs without pressure to get an initial PR ready for exposure on the default/stable cookbook.

[itcarroll]

Just skimming the quarto docs, and I think the mapping I'm thinking of is

• stable = draft-mode: gone
• latest = draft-mode: visible

I suspect we can render both ways under different prefixes.

[ateucher]

@itcarroll are you thinking that we have a stable and latest version of the cookbook as a whole, or for individual pages? I feel like the quarto feature you linked to is for marking individual pages as draft? Which could absolutely be useful

[itcarroll]

I'm not sure I understand how you're seeing things, so feel free to re-ask.

I'm suggesting https://nasa-openscapes.github.io/earthdata-cloud-cookbook/latest/ be the whole cookbook with all drafts visible. Each item you otherwise want hidden would have to include draft: true in its front matter.

[ateucher]

Ok, I've got you now! So we'll have to figure out how to deploy two versions, one with draft-mode: gone and one with draft-mode: visible. And I guess that https://nasa-openscapes.github.io/earthdata-cloud-cookbook/ would redirect to https://nasa-openscapes.github.io/earthdata-cloud-cookbook/latest/

[itcarroll]

I think I've made some headway on this, using a toy repo at https://github.com/itcarroll/versioned-quarto.

Check out https://itcarroll.github.io/versioned-quarto/en/latest/guide.html for a quick demo and description of steps. Same approach might work for the cookbook without a crazy amount of changes.

[itcarroll]

Copy-pasting notes on issues raised during the May 21 cookbook co-working Zoom:

1. possible confusion if people end up at the wrong one.
2. would need a banner on the /latest alerting and pointing to the stable
3. maybe this is not needed, cookbook not quite the same as software where latest docs are tied to code changes that are unreleased
4. latest/stable might be more confusing for readers; different audience than software where people might be anticipating
5. for new contributors, it is nice to see your contribution sooner
6. this is a live resource that we want to be able to correct and update in real time. Starting to manage releases etc adds too much overhead and structure
7. we should write down our publishing process in the cookbook
8. not prioritizing this now would also let us get into the content creation sooner.

I had to leave the meeting before this issue surfaced, so I'm adding some responses. It feels to me like there is a misunderstanding that this feature request is about a release process. The "stable" and "latest" terminology I fell back on is probably misleading for software developers; perhaps a better split is "published" and "draft". I agree we currently do not need a release process (as indicated above).

1. if not viewing a "draft" page, then this is possible. it think it can be mitigated with a "draft" toggle switch like the "dark mode" toggle.
2. see 1, but note that "draft" pages have this banner by default in quarto
3. the "drafts" could very well have code that is unfinished and does not work as intended
4. how about "published" and "drafts"?
5. my proposal is all about getting content on the website sooner! by tagging your work as "draft" you can get it on the website before its completely finished.
6. not proposing a release process. "stable" was misleading terminology to those who know it actually means tagged for a release on github. my bad.
7. sure should
8. this should not hold up any current work on the reorganization