Open Stack

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.

> 
> 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.

> 
> 
> For the future:
> 
> 3. Stop the bit of the redirect business that users don't like and do awesome/best-practice/world-leading things that let users switch between releases for a particular page. This will only be possible with a change in how we work (eg content moves or deletions become a something where consideration is needed for the archive), perhaps more significant than the coding effort required.
> 

The coding effort is already underway to allow people to easily switch between versions (but that's solving a different problem). Brian has been working on this for some time, and I'm sure he'd appreciate your help, if you have code to contribute. If you have a technical solution for creating an archive, please create a spec, and ensure you have people onboard to help implement it.

As you already know, I'm totally OK with process changes, as long as they're improving on what we already have. I think we can come up with a good solution to the archiving problem, but we're only a few weeks out from Ocata and I'm neck-deep in release tasks and testing, so the workaround will have to suffice for the moment. Let's talk further in Pike.

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/2986db56/attachment-0001.pgp>