Open Stack

On 24/01/17 01:19, Andreas Jaeger wrote:
> On 2017-01-23 15:04, Alexandra Settle  wrote:
>> Hi everyone,
>>
>>  
>>
>> I would like to know if we have ever discussed appropriately archiving
>> documentation after EOL date?
>>
>>  
>>
>> Tom triaged this bug
>> https://bugs.launchpad.net/openstack-manuals/+bug/1658659 this morning,
>> where the reporter noted that Icehouse documentation was not found on
>> docs.openstack.org. The reporter noted that it was EOL, but was 404ing
>> and did not redirect to any archive folder.
>>
>>  
>>
>> Normally, I’m not too sure I’d be concerned about documentation as far
>> back as Icehouse but as Tom notes in the bug, “With 9% of users still
>> having Icehouse in production as at October 2016, I tend to agree.” The
>> number of users was something I was unaware of – thank you, Tom.
>>
>>  
>>
>> Did we ever have a process in place to appropriately archive
>> documentation? Was there a reason we do not archive documentation after
>> EOL dates?
> 
> In the past, we just redirected after a release was EOLed all links to
> our home page, like:
> # Redirecting End-of-Life (EOL) versions, see
> https://wiki.openstack.org/wiki/Releases:
> redirectmatch 301 /bexar/.*$ /index.html
> redirectmatch 301 /cactus/.*$ /index.html
> redirectmatch 301 /diablo/.*$ /index.html
> redirectmatch 301 /essex/.*$ /index.html
> redirectmatch 301 /folsom/.*$ /index.html
> redirectmatch 301 /grizzly/.*$ /index.html
> redirectmatch 301 /havana/.*$ /index.html
> So, we just hide all the content.
> 
> This wasn't done for icehouse and newer. We could even close that bug
> with adding a redirect - following our practice for older releases.
> 
>>  
>>
>> If we were to archive documentation, I would recommend something similar
>> to the following:
>>
>> 1.       Anything that is EOL’d is converted to a PDF document by the
>> release team (now we have the functionality to do so).
> 
> This helps going forward with Ocata. It might need some extra work for
> older releases. But a nice idea to investigate further.
>>
>> 2.       EOL branch is deleted as per normal.
>>
>> 3.       Each document is branded with “End of life – cannot be edited”
>> or something of that nature.
>>
>> 4.       Kept in Archive folder on main docs.o.o page.
>>
>>  
>>
>> Thoughts? Or is there a piece of history here that I am missing?
> 
> This all needs to be automated.
> 
> An Archive folder is something we cannot create "manually", it needs to
> be either a script that the infra team can easily run or we publish in
> such a way that this works.
> 
> Also, we should look at docs.openstack.org overall. We should consider
> older developer/nova content as well. Our site was the largest Cloud
> Sites site with over 600,000 files. We cannot archive everything for
> ever! We would need some retention policies on when to really delete the
> archived content.
> 
> And what happens with links to icehouse documentation? Do we redirect
> them to archive?
> 
> Somebody needs to architect a solution and drive it through. This should
> then end in a spec IMHO.
> 
> I'm available to answer questions and comment as needed,
> 
> Andreas

I agree with Andreas that we can't possibly keep everything forever, there's simply too much of it. It also needs to be an automated process, because otherwise there's too much heavy lifting involved. I'm not aware of a solution to this problem. We've been around and around on this for a long time, and each time we stymie ourselves into inaction. I say we add a redirect in order to close the bug (as we have done in the past), and continue waiting until a better long-term solution presents itself.

L
 

-- 
Lana Brindley
Technical Writer
Rackspace Cloud Builders Australia
http://lanabrindley.com

-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 538 bytes
Desc: OpenPGP digital signature
URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20170124/6348ed36/attachment.pgp>