website icon indicating copy to clipboard operation
website copied to clipboard

Use only real version names, not `next`, for doc version subdirectories under /content

Open chalin opened this issue 4 years ago • 6 comments

@spzala et al: I'd like to propose that all our doc version subfolders name the version they are targeting. That is currently the case except for the special /docs/next.

Some drawbacks of using /docs/next as part of permalinks include the following:

  • This muddles analytics
  • It makes releasing a new version of the docs a bit more work. For details, see the following threads:
    • https://github.com/etcd-io/website/pull/203#discussion_r620307379
    • https://github.com/etcd-io/website/pull/203#discussion_r618467132
  • In my opinion, it can confuse site users as explained next: Let's suppose that we just released v3.5 docs, under the current scheme we'd already have a /docs/next even though there are no v3.6.x-DRAFT docs. Under the new scheme we can either, not create v3.6 until we have v3.6 docs, or we can immediately create the branch but mark it as draft and not publish it (until we have actual v3.6 specific changes).

Some advantages of using only a version name for doc-version subfolders:

  • We can have more than one "next". For example, etcd currently has v3.5 and v4.0 under development.

We can, of course, keep /docs/next as a virtual path that is redirected to the/a "next" release of the docs.

Thoughts?

Related:

  • Changing "Next" to "Upcoming version" #220 -- though that issue concerns the displayed name, not permalink segment names.
  • vX.Y.Z doc pages with links into GitHub should link to vX.Y.Z not master #147

Following, #336, we'll need to consider the impact (and possible improvements) to the Makefile.

/cc @nate-double-u

chalin avatar Apr 26 '21 20:04 chalin

Setting e1-hours and p1-high. I don't think this will take that long to do, but it's important that we make a decision around how we name our upcoming versions moving forward.

nate-double-u avatar May 21 '21 19:05 nate-double-u

I agree with the proposal that all our doc version subfolders name the version they are targeting.

nate-double-u avatar May 21 '21 19:05 nate-double-u

Think about this more, an alternative would be to keep next but define a redirect rule based on the eventual version that next will be.

chalin avatar May 21 '21 19:05 chalin

All: as a step in this direction, we'll be implementing the proposal (in the opening comment) as part of the preparation for the v3.5 docs; see #332. /cc @spzala @ptabor

chalin avatar May 28 '21 17:05 chalin

Note, currently there is no next. Since the v3.5 release, next points to the same folder as latest.

nate-double-u avatar Jun 16 '21 18:06 nate-double-u

Related conversation: https://github.com/etcd-io/etcd/pull/13110#issuecomment-862726764 (@ptabor)

nate-double-u avatar Jun 16 '21 22:06 nate-double-u