Archive docs for unsupported versions of CockroachDB

[jseldess]

Jesse Seldess commented:

Currently, our docs cover all historical versions of CockroachDB, from v1.0 to the present. However, our release support policy shows that everything prior to 19.2 is officially unsupported, and we mark docs for versions prior to that with a warning to that effect (example).

We should consider archiving all docs for unsupported versions. Open questions:

• Option 1: Should we keep docs for unsupported version on our site but stop maintaining them?
• Option 2: Should we take these docs off our site and just make the source files available for reference?

The mechanics of option 1 are TBD. Ideally, we would remove the docs from our main repo to dramatically shrink its size and complexity.

Jira Issue: DOC-1011

Jira Issue: DOC-1011

[andreimatei]

Option 1: Should we keep docs for unsupported version on our site but stop maintaining them?

Definitely not option 2, I'd say. Not "supporting" a version doesn't mean deleting the docs :)

[BramGruneir]

Option 1 please. Keep the docs around.

Un-supported doesn't mean that the docs should disappear. I still find them quite useful, especially for determining which feature was added at what release. I wouldn't mind if they're just static pages, but we should ideally keep the CSS matching.

[jseldess]

Thanks, @BramGruneir and @andreimatei. Option 1 does seem more friendly, I agree.

@yingzhuchin, for that option, we should brainstorm how to change our build process. We may want to move archived docs into a separate repo and have a separate build. A branch-based build process would be another way to simplify the docs UX, but it would make maintenance of supported versions more burdensome: https://github.com/cockroachdb/docs/issues/4959. @ianjevans would be a good brainstorming partner on this project.

[bdarnell]

Note that it's fine (at least from my perspective) if older docs are frozen in time and don't get style or other updates. (compare python 2.7 and python 3.9 docs. or even 1.4, the version i originally learned)

but we should ideally keep the CSS matching.

Trying to keep static HTML working with newer CSS is going to be a big headache - if we care about applying new styles to old docs we should just keep building them live (and try to find other solutions to the problems that are solved by deleting old versions, like breaking the build into separate pieces and doing more caching to speed it up when old versions aren't changing).

[ianjevans]

We should look into removing EOL versions of the docs from the main docs repo. We don't have the concept of doc archives where users can browse old docs but the docs team doesn't touch.

Because of how we organize the docs repo, every six months we add a new set and it's starting to impact build times and link checks, etc.

I think we should build a simplified stripped-down HTML version of the EOL docs, and make them not dependent on current company branding and style CSS. As new versions go to EOL, we can move them to the archive.

[jseldess]

Just looked at pageviews across all version of our docs since 1/1/22:

version	pageviews
v1.0	95
v1.1	143
v2.0	268
v2.1	684
v19.1	1182
v19.2	4718
v20.1 (EOL)	8365
v20.2	8812
v21.1	15,697
v21.2/stable	575,414
v22.1/dev	2825

[exalate-issue-sync[bot]]

Dan Kelly (dankellycockroach) commented: Ian Evans that is an interesting suggestion you made on June 10th, 2022. What was the reason you mentioned it?

I’ve been looking for a solution that does the most good and the least harm (SEO wise). Right now the docs versions are considered duplicative content and it’s hurting our traffic.

[exalate-issue-sync[bot]]

Ian Evans (ianjevans) commented: Dan Kelly The motivation is mostly to address internal organization problems with including so many versions of the docs within the same repo, and to reduce build latencies for CI/CD. Every 6 months we add a new major version of CRDB, which means copying the entire docset over to a new root dir.

With that said, if we can also improve SEO that’s an additional impetus to treat EOSL docs differently. Nick Vigilante thoughts?

[exalate-issue-sync[bot]]

Nick Vigilante (nickvigilante) commented: Ian Evans Dan KellyAn idea that just came to mind: we spin up a second subdirectory at the same level as /docs or one level down (archived-docs, for example) for everything that has expired. That way, we can hopefully optimize SEO for everything with the URL cockroachlabs.com/docs and ignore everything with the docs-archived subdirectory. Build times will remain pretty static, we won’t have to worry too much about formatting or includes, the docs will still be usable, and the traffic will be divided between archived content (that hopefully we don’t really care about) and current traffic.