On 2017-07-28 01:10, Doug Hellmann wrote:
> Excerpts from Doug Hellmann's message of 2017-07-27 19:05:16 -0400:
>> Excerpts from Jeremy Stanley's message of 2017-07-27 22:07:33 +0000:
>>> On 2017-07-27 15:40:22 -0400 (-0400), Doug Hellmann wrote:
>>> [...]
>>>> Are we over-emphasizing the scale of the discovery problem?
>>>>
>>>> When I search for how to install a package on Ubuntu (or Red Hat
>>>> or Debian for that matter), I find all sorts of references all over
>>>> the web (including on the sites for those distros) and I have to
>>>> sift through it all to find right command or package name to use
>>>> for my version. Usually the easiest way to do that is to put the
>>>> version in the search query.
>>>>
>>>> Are our users incapable of finding the right version of a document
>>>> if we clearly mark the version to which each document applies? Every
>>>> URL now has a release series name or version tag in the path. The
>>>> docs theme inserts the version number into every page as well. Is
>>>> that sufficient to help a reader understand what version the info
>>>> they're view is for?
>>>>
>>>> That's not to say we shouldn't do some work to make newer docs easy
>>>> to find. If we can modify the sitemap to make them appear earlier
>>>> in search results, that's good. The docs theme allows a project to
>>>> include links to several older versions to switch between them,
>>>> too, so users who land on the "wrong" version can switch. We could
>>>> update that to include branches as well as tags, so that someone
>>>> can easily move to the series they need without knowing the version
>>>> number.
>>> [...]
>>>
>>> The biggest liability is people not realizing there are multiple
>>> "versions" of OpenStack finding an old install doc and using it
>>> because they don't know it's out of date, then seeking support
>>> upstream or just generally contributing to the number of deployments
>>> unnecessarily stuck on obsolete software. The current solution of
>>> not publishing installation guides for EOL releases seems like a
>>> good enough compromise there to me.
>>
>> That content will now live in the project trees. Perhaps part of marking
>> branches in those repos EOL needs to include deleting the install tree
>> from the docs? Now that the docs are in a standard location, that could
>> be part of an EOL script (although it means 2 phases, since we have to
>> land the patch and let the docs rebuild before we remove the branch).
>>
>> We could also update the openstack-manuals tree to not publish links
>> to the install guides (either removing the page or replacing it
>> with a placeholder that explains they should be trying to use a
>> newer version).
>>
>> Doug
>>
>
> Today we're publishing series-specific (e.g., newton) and
> version-specific (e.g., 10.0.0) docs. I wonder if we should stop
> publishing docs when we tag repositories, and just stick to the
> series? There's no way to go back and update those version-specific
> builds after the fact, so we can't remove the installation guides
> and we can't rebuild them easily if there are security issues with
> the content.
Sorry, send my other email before reading the whole thread. But reading
this, let me add one more line:
The publishing when tagging was needed for the client libraries that we
only published when tagging. Now we publish *all* docs after each merge.
So, I agree, we can remove the building at tag time,
Andreas
--
Andreas Jaeger aj@{suse.com,opensuse.org} Twitter: jaegerandi
SUSE LINUX GmbH, Maxfeldstr. 5, 90409 Nürnberg, Germany
GF: Felix Imendörffer, Jane Smithard, Graham Norton,
HRB 21284 (AG Nürnberg)
GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126
__________________________________________________________________________
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
