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