Project

General

Profile

Documentation #7886

What's the policy on URL stability for public documentation?

Added by Yan-Fa Li about 10 years ago. Updated over 4 years ago.

Status:
New
Priority:
Normal
Assignee:
Category:
documentation
Target version:
-
% Done:

0%

Tags:
Backport:
Reviewed:
Affected Versions:
Pull request ID:

Description

We're trying to decide whether to include links to documentation on ceph.com within the UI of the Calamari product. What's the policy at ceph.com for the stability of links? Is there a permalink to the most current version of the ceph documentation that is safe to use within a web page?

Should we include a full copy of the ceph sphinx docs within an ICE release for offline use and/or avoid the issue with stable URLs?

History

#1 Updated by John Wilkins almost 10 years ago

  • Status changed from New to 4
  • Assignee changed from John Wilkins to Neil Levine

The Ceph.com site uses the master branch by default, which changes somewhat frequently. A more stable approach would be to ensure that the URL you expect to bake into a release works properly on the "next" branch, but specify the point release. For example, for Ceph version 0.71, the URL would look like this: http://ceph.com/docs/v0.71/ We don't regularly update the versioned branches, so they are more stable over the long term.

#2 Updated by Neil Levine almost 10 years ago

  • Assignee changed from Neil Levine to John Wilkins

Getting off master and using the last named release branch name as the default docs root makes total sense. Does sphinx allow us to do something more sophisticated, like having a 'latest' link that points to the most recent branch? We can then point the webpage link to that.

#3 Updated by Dan Mick almost 10 years ago

We could certainly have a "latest-release" link on the website and legislate that to be our 'stable' doc link...

#4 Updated by Patrick Donnelly over 4 years ago

  • Status changed from 4 to New

Also available in: Atom PDF