1. posterid:1845740
  2. Fabric v1.1, v1.2, v1.3 documentation

Re: Fabric v1.1, v1.2, v1.3 documentation

Brett T Logan <brett.t.logan@...>
 

I just had a discussion with Pam and I proposed a solution that I thought might solve both of these problems. When we retire doc, we can use GitHub Pages to post their final form. We then add a `Legacy Documentation` page to Read The Doc's and anyone who lands on a retired RTD page would be redirected to the `Legacy Documentation` page. The page would include all relevant information, such as:
 
"The version of the documentation you were attempting to access is for an unsupported version of Hyperledger Fabric and has been retired. We highly recommend you use a supported version of Fabric and it's corresponding documentation. If you still must access one of our legacy documentation pages, you can find them at the links below."
 
The user could then use one of these links to still access the legacy doc, but not without being forced to read the warning first.
 
Adding red banners to the top of all of the pages isn't a straight-forward task with our existing doc, and I know I tend to totally ignore anything I'm not interested in. And anyone who is using an Anchor Link wouldn't be directed to the top of the page anyway and would miss the banner.
 
Brett Logan
Software Engineer, IBM Blockchain
Phone: 1-984-242-6890
 
 
 

----- Original message -----
From: "Brian Behlendorf" <bbehlendorf@...>
Sent by: fabric@...
To: fabric@...
Cc:
Subject: [EXTERNAL] Re: [Hyperledger Fabric] Fabric v1.1, v1.2, v1.3 documentation
Date: Tue, Sep 1, 2020 2:13 AM
 
I do not think it is ever wise to remove old documentation, even with automated redirection. There are valid use cases for examining old docs, from understanding how a feature evolved or was first introduced, to helping that poor kid who was dropped into fixing a downtime issue on a production platform that the kid's predecessors didn't upgrade as they should. I often have to go find online user manuals for old hardware long out of warranty or support. I realize those docs are in Github so they're not disappeared entirely (nor of course from the Internet Archive), but for both those use cases, reading through the source trees or doing a local build of the docs is pretty cumbersome. I'd sooner recommend a big red banner across the top declaring them out of support and that the authors urgently recommend the reader upgrades to a supported release.
 
Brian
 
On 8/31/20 12:02 PM, Pam Andrejko wrote:

As Joe mentioned on the last Contributor's call,  we’ve noticed from Google Analytics of the Fabric documentation that there are still readers viewing older versions of the documentation and we'd like to propose a strategy for retiring old versions from ReadTheDocs. The strategy we are proposing here aligns with the overall Fabric LTS strategy, where two LTS releases overlap so that users can make plans to upgrade to the latest LTS release.

Following the same approach, the documentation proposal is to keep the documentation for the current LTS version, and for prior versions, back to the previous LTS version. Currently, that would include v2.2 (current LTS), v2.1, v2.0, and v1.4 (previous LTS). This approach would imply removing the v1.1, v1.2, and v1.3 documentation versions, since these versions are no longer supported, and adding redirects to the latest documentation in ReadTheDocs.

I should emphasize that there are no plans to remove the source code branches on Github for those previous Fabric versions. And because the documentation is included in the source code, the older documentation will remain available in Github for historical reference. The intent here is only to remove the unsupported versions from ReadTheDocs to encourage users to utilize one of the more recent versions.

 

Pam Andrejko

 

--
Brian Behlendorf
Executive Director, Hyperledger
bbehlendorf@...
Twitter: @brianbehlendorf
 
Join fabric@lists.hyperledger.org to automatically receive all group messages.