[OpenStack-docs] [openstack-docs] Archiving documentation

Tom Fifield tom at openstack.org
Tue Jan 24 12:44:00 UTC 2017


Top posting with intent :)

We have someone who is representing a class of people that are almost 
certainly more than 5% of our users and we chose not to help? No two 
ways about it - with the minimal/once-off effort involved, that is just 
plain wrong.

To fix Icehouse docs not existing, all one would need to do is copy from 
the old server to the new. We broke this, and we should fix it.

Docs team, please listen to your users - you've had more engagement on 
this point than many others. It's a real issue, and it needs solving.


Regards,


Tom


On 24/01/17 20:27, Alexandra Settle wrote:
> I agree with Lana. Unfortunately, as much as I like the idea of a solution – but it’s hard.
>
> I am closing the Icehouse bug with a ‘Won’t Fix’ unless someone would like to take on board the planning and execution of a potential solution.
>
> On that note – we do need to ensure all our redirects are in place: https://bugs.launchpad.net/openstack-manuals/+bug/1621685
>
> Andreas – what do we need to do to ensure all redirects are up and running? Can you run a scrappy on this? Let’s ensure (at the very least) our 404s are at a minimum.
>
> On 1/23/17, 11:41 PM, "Lana Brindley" <openstack at lanabrindley.com> wrote:
>
>     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
>
>
>
> _______________________________________________
> OpenStack-docs mailing list
> OpenStack-docs at lists.openstack.org
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs
>




More information about the OpenStack-docs mailing list