Version-agnostic docs and their handling

[mightyiam]

Hi and thank you for rtfd.

I've a question about page redirects and how I can get the right kind of setup I want.

Also, a more general question about documentation arises from this (or the other way around).

I'll start with the general question.

I've found a certain quality that some versioned software documentation pages have.
This quality is being version-specific.

Some pages are version-specific and some pages are not version specific.

For example, API docs, are inherently version-specific. When reading API docs, one always reads the version of the docs that corresponds with the version of the software.

On the other hand, version-agnostic docs do not benefit from existing in multiple version, each corresponding to its software version.

An example of version agnostic docs is "Upgrading to v2".
In "Upgrading to v2", there are tips on upgrading to v2 (from v1) of the software and a list of backwards incompatible changes that one may have to deal with when upgrading.

"Upgrading to v2" should always be read at the latest version. Having multiple versions of it does not help. On the contrary. If it is bound to VCS and the release cycle, perhaps it was first released in v2.0.0 and then updated with useful information derived from user experiences in v2.1.0. This would make the v2.0.0 of "Upgrading to v2" obsolete and not in a manner similar to, for example, v2.0.0 of the API docs―those are required for users who have not yet upgraded to v2.1.0.

The obsolescence of v2.0.0 of "Upgrading to v2" is total. It is not only less useful than its newer version, it is also preferably just made hard to reach, making sure that everyone gets to read the newer version.

So far, is everyone on board with this distinction and the conclusions?

My question is how can I, as a user of rtfd, can make sure that users reading my "Upgrading to v2" page are reading the latest version?

I thought about putting it in the project's wiki but that cuts our project's code review process into two and lacks all the other benefits of managing the docs in VCS/GitHub.

[ericholscher]

Fabric did this in an interesting way with:

http://www.fabfile.org/ - as the "versionless" docs
http://docs.fabfile.org/en/1.10/ - as the "versioned" docs

I believe they are different repos, and interlink.

[mightyiam]

@ericholscher I appreciate your response.

It seems that indeed they have solved it in some way.

The two documentations are in the same repo.

• the wwww
• the docs

The www is built from master and the docs are built from each version, I am assuming.

That is a very simple solution, if they are comfortable with it. For example, if you have a site that's built with sphinx.

What if we prefer to keep all of the docs in rtfd? I imaging that this can be made by having two different documentations in rtfd but links from the versionless docs to the versioned docs will point to the default version and that can be confusing if you haven't noticed that there are two different docs.

Is there a way to solve this in one documentation in rtfd?

[mightyiam]

I'm thinking perhaps if there's a custom redirects feature, this can be quite easy. Just redirect all the versionless pages to the latest version. But then the reader may find himself on a different version and not knowing why. Or worse, now realizing that he's on a different version than what he was in just a moment ago.

[ericholscher]

Fabric is using Read the Docs for their documentation, so yes it's possible
:)

On Tue, Jul 28, 2015 at 11:19 AM, Shahar Or [email protected]
wrote:

@ericholscher https://github.com/ericholscher I appreciate your
response.

It seems that indeed they have solved it in some way.

The two documentations are in the same repo.

• the wwww
  https://github.com/fabric/fabric/blob/master/sites/www/index.rst
• the docs
  https://github.com/fabric/fabric/blob/master/sites/docs/index.rst

The www is built from master and the docs are built from each version, I
am assuming.

That is a very simple solution, if they are comfortable with it. For
example, if you have a site that's built with sphinx.

What if we prefer to keep all of the docs in rtfd? I imaging that this can
be made by having two different documentations in rtfd but links from the
versionless docs to the versioned docs will point to the default version
and that can be confusing if you haven't noticed that there are two
different docs.

Is there a way to solve this in one documentation in rtfd?

—
Reply to this email directly or view it on GitHub
#1493 (comment)
.

Eric Holscher
Maker of the internet residing in Portland, Oregon
http://ericholscher.com

[gregmuellegger]

@mightyiam has eric's suggestions helped you out on what you wanted to achieve? Closing this due to inactivity. Please open a new ticket if it's still an issue for you.

[mightyiam]

Nope. What I would like is for certain pages to be version agnostic. I resorted to a simple included message, like on this page (source).

But the concept seems to me prevalent enough for a built in solution.