Open Stack

On 25/01/17 14:39, Tom Fifield wrote:
> On 25/01/17 12:33, Lana Brindley wrote:
>> On 25/01/17 14:25, Tom Fifield wrote:
>>> On 25/01/17 08:05, Lana Brindley wrote:
>>>> On 25/01/17 00:00, Tom Fifield wrote:
>>>>> On 24/01/17 21:36, Andreas Jaeger wrote:
>>>>>> On 2017-01-24 14:22, Tom Fifield  wrote:
>>>>>>> On 24/01/17 20:53, Andreas Jaeger wrote:
>>>>>>>> On 2017-01-24 13:48, Tom Fifield  wrote:
>>>>>>>>> On 24/01/17 20:47, Andreas Jaeger wrote:
>>>>>>>>>> On 2017-01-24 13:44, Tom Fifield  wrote:
>>>>>>>>>>> Top posting with intent :)
>>>>>>>>>>>
>>>>
>>>>
>>>> <snip>
>>>>
>>>>>
>>>>>> Tom, I'd rather fix the general problem instead of fighting single
>>>>>> fires. So, what's the proposal you want to make for older documentation
>>>>>> and how can we implement that - and retire it?
>>>>>
>>>>> For now, what I would recommend is:
>>>>>
>>>>> 0. Acknowledge the install guide as special and basically that guide should follow upstream EOL. Any new installs should be a supported version - helping people keep existing clouds going is the primary archive interest for upstream EOL'd releases.
>>>>
>>>> We already do this.
>>>>
>>>>>
>>>>> 1. For other guides, keep the docs (in place, same URLs etc) for a version around until there aren't enough users on the version to warrant it, based on user survey data. (This includes fixing any versions broken by the server move)
>>>>
>>>> First of all, we need to determine what an appropriate threshold is. 5%? 100 installs? 100 hits? Do we count PoC installs, or just production? Do we count a hit if the bounce rate is high? Then, we need to find a human to monitor these statistics and alert the infra/tools team once a release drops below the threshold. *Then* we need to engage whatever mechanism we have implemented to archive those old docs. It's not an impossibility, but it's labour intensive, not able to be automated, and prone to breakage when humans get bored and wander off. That's a lot of red flags to me.
>>>
>>> Not a problem. Take a conservative number to start with - 5%, production installs. That's more than 100 clouds. It also happens to be a bit less than the Icehouse number.
>>>
>>> This need only be revisited that twice a year, when the survey data is released.
>>>
>>> The current "archive" process - deleting a release directory - isn't particularly onerous. In fact, it's similar in effort to the solution for the current issue. Noone's asking for anything "labor intensive" here - to fix the problem that was created by the server move requires only a simply copy from one server to another. I'd say about 15 minutes.
>>>
>>
>> Is that you volunteering to do it?
>>
>>>>>
>>>>> 2. We don't touch anything for the EOL'd stuff. Incoming bugs on EOL'd versions are closed as wontfix. If something for an old version goes very wrong and it stops publishing, we might abandon it, or throw up a redirect to a PDF or something.
>>>>
>>>> Right now, we have exactly one bug asking for old versions, and we have implemented a workaround. That is all we are realistically able to do at this point in the release cycle. I personally like the solution of having an archive of PDF versions, with appropriate disclaimers as a watermark, and using redirects to point to them. However, since we only recently got PDF generation working, this solution may take some time to implement. It also doesn't address the fact that the archive is going to get very large, very fast. PDFs don't compress well. In short, I think there's a solution here, I'm just not certain what it is yet.
>>>
>>> As above, it's not a fix. People trying to run their clouds are doing so without documentation at the moment, and the docs team has the capability to help with very little effort. The bug tracker argument is a red herring when you have far better data available from the user survey. It helps to think bigger picture than just docs or its tracker and understand how users select and migrate between versions.
>>>
>>> To fix this requires 15 minutes of effort to copy some HTML pages from one server to another - to solve a problem that was created by the server move.
>>
>> Again, are you offering?
> 
> I'd suggest that anyone on the infrastructure team would be happy to perform this copy (and have the access necessary to do so. Just drop a mail to openstack-infra at lists.openstack.org (or in #openstack-infra) and ask to copy the icehouse dir from 'docs-archived' to 'docs.o.o'.
> 

I don't just mean doing the copy. I mean maintaining it over time. You need to keep an eye on the stats, and make the request to archive when the time comes.

I would also like the team to agree on 5% of production installs as a base for archiving, too.

Lana


-- 
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/20170125/96797014/attachment-0001.pgp>