Open Stack

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.

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


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

This is not some massive process change. It's a simple 15 minute task to 
help real users who are trying to do their job, made more difficult 
without a valid reason by the docs team. Fixing it is certainly an 
improvement on what we already have - providing a terrible experience to 
a good deal of people.


Please listen to your users. Reach out to them pro-actively as other 
teams do. Validate proposed methods and changes with them. Helping your 
users with quick action should not require as much discussion as this :)