Re: [openstack-dev] [docs][release][stable][ptl][infra] Strategic discussion regarding the future of documentation for EOL releases
On Thu, Aug 03, 2017 at 11:10:49AM -0400, Doug Hellmann wrote: > Excerpts from Tony Breeds's message of 2017-08-03 12:20:24 +1000: > > On Thu, Jul 27, 2017 at 07:05:16PM -0400, Doug Hellmann wrote: > > > > > 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). > > > > That can be done. It's a bit of a pain but for the most part the gate > > is pretty stable at EOL time. I do worry about what we do if $projects > > gate is broken and can't generate/publish the docs. > > > > > 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). > > > > That'd work too. I kinda like that option better. > > Yes, that's easy to do with 1 patch to the openstack-manuals repo. We can work that into the EOL process if everyone is okay with that approach. Yours Tony. signature.asc Description: PGP signature __ 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
Re: [openstack-dev] [docs][release][stable][ptl][infra] Strategic discussion regarding the future of documentation for EOL releases
Excerpts from Tony Breeds's message of 2017-08-03 12:20:24 +1000: > On Thu, Jul 27, 2017 at 07:05:16PM -0400, Doug Hellmann wrote: > > > 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). > > That can be done. It's a bit of a pain but for the most part the gate > is pretty stable at EOL time. I do worry about what we do if $projects > gate is broken and can't generate/publish the docs. > > > 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). > > That'd work too. I kinda like that option better. Yes, that's easy to do with 1 patch to the openstack-manuals repo. 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
Re: [openstack-dev] [docs][release][stable][ptl][infra] Strategic discussion regarding the future of documentation for EOL releases
On Thu, Jul 27, 2017 at 07:05:16PM -0400, Doug Hellmann wrote: > 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). That can be done. It's a bit of a pain but for the most part the gate is pretty stable at EOL time. I do worry about what we do if $projects gate is broken and can't generate/publish the docs. > 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). That'd work too. I kinda like that option better. Yours Tony. signature.asc Description: PGP signature __ 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
Re: [openstack-dev] [docs][release][stable][ptl][infra] Strategic discussion regarding the future of documentation for EOL releases
Excerpts from Doug Hellmann's message of 2017-07-31 10:02:19 -0400: > Excerpts from Doug Hellmann's message of 2017-07-27 19:10:32 -0400: > > 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 +: > > > > 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 > > > > I've proposed https://review.openstack.org/489231 to update > project-config to stop publishing docs when we tag releases. > > Doug > And here's the theme change to show series names instead of version numbers: https://review.openstack.org/489252 __ 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
Re: [openstack-dev] [docs][release][stable][ptl][infra] Strategic discussion regarding the future of documentation for EOL releases
Excerpts from Doug Hellmann's message of 2017-07-27 19:10:32 -0400: > 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 +: > > > 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 > I've proposed https://review.openstack.org/489231 to update project-config to stop publishing docs when we tag releases. 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
Re: [openstack-dev] [docs][release][stable][ptl][infra] Strategic discussion regarding the future of documentation for EOL releases
+2 I am in support of this approach. It is clear that people are still looking for content from older releases long after it has been released but making it clearer that it is an EOL release is an improvement. Jay On 7/28/2017 4:38 AM, Thierry Carrez wrote: Andreas Jaeger wrote: On 2017-07-27 21:40, Doug Hellmann wrote: [...] Please encourage everyone there to explore options that require the least amount of effort. An ideal solution is one we can implement without heroic efforts or having to recruit an army of contributors. I agree with the points made in general and want to stress we need something that reduces our efforts. Yes, agree on the general idea of keeping docs around "forever". Two more ideas: 1) What about enhancing the openstackdocstheme to automatically add a watermark if we publish a stable branch document? Like on https://docs.openstack.org/mitaka/config-reference/ - which also includes a warning that the branch is EOL. What about adding at *start* of a branch a message to the index page like "This is the document for the SERIES release. Please see https://releases.openstack.org/ whether the SERIES release is still supported by the OpenStack community." That would be a great way of ensuring that old content is not mistaken for currently-maintained content, encouraging old users to migrate to newer / better-supported versions. 2) The openstackdocstheme has the report a bug link feature. We can disable this. If we EOL docs (so, push a change before we eol them), we could remove the setting so that "report a bug" does not work. Cheers, __ 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
Re: [openstack-dev] [docs][release][stable][ptl][infra] Strategic discussion regarding the future of documentation for EOL releases
On Fri, Jul 28, 2017 at 07:39:25PM +, Jeremy Stanley wrote: > On 2017-07-28 15:32:01 -0400 (-0400), David Desrosiers wrote: > [...] > > I am very opposed to removing subsets of docs, including the install guide, > > after the release goes eol upstream from consumers for exactly that reason. > > > > Watermarking the upstream docs with series and version should reduce or > > eliminate the need for people to incorrectly submit fixes, patches and PRs > > for eol releases that the core team can no longer support, but that > > shouldn't necessitate removal of the installation instructions. > > Perhaps a compromise is to add very visible banners that explicitly > remind the reader they're looking at installation instructions for > an outdated version of the software, with a link to see the current > installation instructions instead? Simply relying on newcomers to > recognize release series names and inherently know whether they're > reading the latest version is an issue. > -- > Jeremy Stanley +1 to this. I think it would be useful to keep the older docs available, and having something very visible letting folks know when they come across them by chance, with pointers to the current info, seems like a good way to handle things. Sean __ 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
Re: [openstack-dev] [docs][release][stable][ptl][infra] Strategic discussion regarding the future of documentation for EOL releases
On 2017-07-28 15:37:07 -0400 (-0400), David Desrosiers wrote: [...] > You could compress the individual files, configure the webserver to send > the correct encoding (Content-Encoding: gzip or deflate) to the client > (assuming their browser sends the correct Accept-Encoding header) which can > then correctly unpack the content for view. > > Lots of ways to shave down the capacity of the data-at-rest on the server. Agreed, but realistically we're one or two orders of magnitude away from needing to worry about that at the moment so should focus on more pressing issues. -- Jeremy Stanley signature.asc Description: Digital signature __ 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
Re: [openstack-dev] [docs][release][stable][ptl][infra] Strategic discussion regarding the future of documentation for EOL releases
Maybe we could just ban search engines from indexing the releases using robots.txt once they go EOL. That would solve the problem of losing old information for people that still need it while preventing people stumbling onto old docs when they search for something. On Fri, Jul 28, 2017 at 12:39 PM, Jeremy Stanley wrote: > On 2017-07-28 15:32:01 -0400 (-0400), David Desrosiers wrote: > [...] > > I am very opposed to removing subsets of docs, including the install > guide, > > after the release goes eol upstream from consumers for exactly that > reason. > > > > Watermarking the upstream docs with series and version should reduce or > > eliminate the need for people to incorrectly submit fixes, patches and > PRs > > for eol releases that the core team can no longer support, but that > > shouldn't necessitate removal of the installation instructions. > > Perhaps a compromise is to add very visible banners that explicitly > remind the reader they're looking at installation instructions for > an outdated version of the software, with a link to see the current > installation instructions instead? Simply relying on newcomers to > recognize release series names and inherently know whether they're > reading the latest version is an issue. > -- > Jeremy Stanley > > __ > 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 > > __ 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
Re: [openstack-dev] [docs][release][stable][ptl][infra] Strategic discussion regarding the future of documentation for EOL releases
On 2017-07-28 15:32:01 -0400 (-0400), David Desrosiers wrote: [...] > I am very opposed to removing subsets of docs, including the install guide, > after the release goes eol upstream from consumers for exactly that reason. > > Watermarking the upstream docs with series and version should reduce or > eliminate the need for people to incorrectly submit fixes, patches and PRs > for eol releases that the core team can no longer support, but that > shouldn't necessitate removal of the installation instructions. Perhaps a compromise is to add very visible banners that explicitly remind the reader they're looking at installation instructions for an outdated version of the software, with a link to see the current installation instructions instead? Simply relying on newcomers to recognize release series names and inherently know whether they're reading the latest version is an issue. -- Jeremy Stanley signature.asc Description: Digital signature __ 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
Re: [openstack-dev] [docs][release][stable][ptl][infra] Strategic discussion regarding the future of documentation for EOL releases
On Thu, Jul 27, 2017 at 8:16 PM, Sean McGinnis wrote: > I like this approach. With the size being manageable (large, but > manageable), I would prefer we leave it until we need to free up > some of the space You could compress the individual files, configure the webserver to send the correct encoding (Content-Encoding: gzip or deflate) to the client (assuming their browser sends the correct Accept-Encoding header) which can then correctly unpack the content for view. Lots of ways to shave down the capacity of the data-at-rest on the server. __ 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
Re: [openstack-dev] [docs][release][stable][ptl][infra] Strategic discussion regarding the future of documentation for EOL releases
On Thu, Jul 27, 2017 at 6:07 PM, Jeremy Stanley wrote: > The current solution of not publishing installation guides for EOL > releases seems like a > good enough compromise there to me. > This then breaks fidelity for those operators who need to either reinstall their existing environment, which may be based on an eol or LTS supported version of OpenStack, or for those who need to fully document their existing, running install. I am very opposed to removing subsets of docs, including the install guide, after the release goes eol upstream from consumers for exactly that reason. Watermarking the upstream docs with series and version should reduce or eliminate the need for people to incorrectly submit fixes, patches and PRs for eol releases that the core team can no longer support, but that shouldn't necessitate removal of the installation instructions. __ 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
Re: [openstack-dev] [docs][release][stable][ptl][infra] Strategic discussion regarding the future of documentation for EOL releases
Excerpts from Jeremy Stanley's message of 2017-07-28 13:23:32 +: > On 2017-07-28 08:34:18 -0400 (-0400), Doug Hellmann wrote: > [...] > > I wasn't able to come up with a way to disable the link without > > triggering a new build. I didn't want us to have to land a patch in each > > repo as part of marking it EOL, but if we're going to do that to remove > > the installation guide anyway then maybe we can disable the bug link at > > the same time. > > Could you have the buglink in the docs go to a centrally-managed, > pattern-based redirect per series and then change that redirect to > point them all to a page describing the EOL process later? Oh, that's an interesting idea. We could do that in the openstack-manuals repo and generate new redirects when we change the status of the series there. 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
Re: [openstack-dev] [docs][release][stable][ptl][infra] Strategic discussion regarding the future of documentation for EOL releases
On 2017-07-28 08:34:18 -0400 (-0400), Doug Hellmann wrote: [...] > I wasn't able to come up with a way to disable the link without > triggering a new build. I didn't want us to have to land a patch in each > repo as part of marking it EOL, but if we're going to do that to remove > the installation guide anyway then maybe we can disable the bug link at > the same time. Could you have the buglink in the docs go to a centrally-managed, pattern-based redirect per series and then change that redirect to point them all to a page describing the EOL process later? -- Jeremy Stanley signature.asc Description: Digital signature __ 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
Re: [openstack-dev] [docs][release][stable][ptl][infra] Strategic discussion regarding the future of documentation for EOL releases
Excerpts from Dmitry Tantsur's message of 2017-07-28 12:29:29 +0200: > On 07/28/2017 09:12 AM, Andreas Jaeger wrote: > > On 2017-07-27 21:40, Doug Hellmann wrote: > >> [...] > >> Please encourage everyone there to explore options that require the > >> least amount of effort. An ideal solution is one we can implement > >> without heroic efforts or having to recruit an army of contributors. > > > > I agree with the points made in general and want to stress we need > > something that reduces our efforts. > > > > Two more ideas: > > > > 1) What about enhancing the openstackdocstheme to automatically add a > > watermark if we publish a stable branch document? > > Like on https://docs.openstack.org/mitaka/config-reference/ - which also > > includes a warning that the branch is EOL. What about adding at *start* > > of a branch a message to the index page like "This is the document for > > the SERIES release. Please see https://releases.openstack.org/ whether > > the SERIES release is still supported by the OpenStack community." > > Or we can use a similar approach with repository badges, and include an image > with URL like https://releases.openstack.org/is-supported/ocata.png, which > will > turn red when ocata goes EOL. Ooo, I like *that*. It lets us generate the updated status badge from a repo that will always be active and isn't likely to get into a state where we can't land patches, like some of our older stable branches have a tendency to do. 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
Re: [openstack-dev] [docs][release][stable][ptl][infra] Strategic discussion regarding the future of documentation for EOL releases
Excerpts from Andreas Jaeger's message of 2017-07-28 09:12:59 +0200: > On 2017-07-27 21:40, Doug Hellmann wrote: > > [...] > > Please encourage everyone there to explore options that require the > > least amount of effort. An ideal solution is one we can implement > > without heroic efforts or having to recruit an army of contributors. > > I agree with the points made in general and want to stress we need > something that reduces our efforts. > > Two more ideas: > > 1) What about enhancing the openstackdocstheme to automatically add a > watermark if we publish a stable branch document? > Like on https://docs.openstack.org/mitaka/config-reference/ - which also > includes a warning that the branch is EOL. What about adding at *start* > of a branch a message to the index page like "This is the document for > the SERIES release. Please see https://releases.openstack.org/ whether > the SERIES release is still supported by the OpenStack community." I like that. We could add that information to a sidebar or footer on every page. > 2) The openstackdocstheme has the report a bug link feature. We can > disable this. If we EOL docs (so, push a change before we eol them), we > could remove the setting so that "report a bug" does not work. I wasn't able to come up with a way to disable the link without triggering a new build. I didn't want us to have to land a patch in each repo as part of marking it EOL, but if we're going to do that to remove the installation guide anyway then maybe we can disable the bug link at the same time. 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
Re: [openstack-dev] [docs][release][stable][ptl][infra] Strategic discussion regarding the future of documentation for EOL releases
On 07/28/2017 09:12 AM, Andreas Jaeger wrote: On 2017-07-27 21:40, Doug Hellmann wrote: [...] Please encourage everyone there to explore options that require the least amount of effort. An ideal solution is one we can implement without heroic efforts or having to recruit an army of contributors. I agree with the points made in general and want to stress we need something that reduces our efforts. Two more ideas: 1) What about enhancing the openstackdocstheme to automatically add a watermark if we publish a stable branch document? Like on https://docs.openstack.org/mitaka/config-reference/ - which also includes a warning that the branch is EOL. What about adding at *start* of a branch a message to the index page like "This is the document for the SERIES release. Please see https://releases.openstack.org/ whether the SERIES release is still supported by the OpenStack community." Or we can use a similar approach with repository badges, and include an image with URL like https://releases.openstack.org/is-supported/ocata.png, which will turn red when ocata goes EOL. 2) The openstackdocstheme has the report a bug link feature. We can disable this. If we EOL docs (so, push a change before we eol them), we could remove the setting so that "report a bug" does not work. Andreas __ 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
Re: [openstack-dev] [docs][release][stable][ptl][infra] Strategic discussion regarding the future of documentation for EOL releases
Andreas Jaeger wrote: > On 2017-07-27 21:40, Doug Hellmann wrote: >> [...] >> Please encourage everyone there to explore options that require the >> least amount of effort. An ideal solution is one we can implement >> without heroic efforts or having to recruit an army of contributors. > > I agree with the points made in general and want to stress we need > something that reduces our efforts. Yes, agree on the general idea of keeping docs around "forever". > Two more ideas: > > 1) What about enhancing the openstackdocstheme to automatically add a > watermark if we publish a stable branch document? > Like on https://docs.openstack.org/mitaka/config-reference/ - which also > includes a warning that the branch is EOL. What about adding at *start* > of a branch a message to the index page like "This is the document for > the SERIES release. Please see https://releases.openstack.org/ whether > the SERIES release is still supported by the OpenStack community." That would be a great way of ensuring that old content is not mistaken for currently-maintained content, encouraging old users to migrate to newer / better-supported versions. > 2) The openstackdocstheme has the report a bug link feature. We can > disable this. If we EOL docs (so, push a change before we eol them), we > could remove the setting so that "report a bug" does not work. Cheers, -- Thierry Carrez (ttx) __ 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
Re: [openstack-dev] [docs][release][stable][ptl][infra] Strategic discussion regarding the future of documentation for EOL releases
On 2017-07-27 21:40, Doug Hellmann wrote: > [...] > Please encourage everyone there to explore options that require the > least amount of effort. An ideal solution is one we can implement > without heroic efforts or having to recruit an army of contributors. I agree with the points made in general and want to stress we need something that reduces our efforts. Two more ideas: 1) What about enhancing the openstackdocstheme to automatically add a watermark if we publish a stable branch document? Like on https://docs.openstack.org/mitaka/config-reference/ - which also includes a warning that the branch is EOL. What about adding at *start* of a branch a message to the index page like "This is the document for the SERIES release. Please see https://releases.openstack.org/ whether the SERIES release is still supported by the OpenStack community." 2) The openstackdocstheme has the report a bug link feature. We can disable this. If we EOL docs (so, push a change before we eol them), we could remove the setting so that "report a bug" does not work. 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
Re: [openstack-dev] [docs][release][stable][ptl][infra] Strategic discussion regarding the future of documentation for EOL releases
On 2017-07-27 21:40, Doug Hellmann wrote: > [...] > Regarding point 2, if we don't have the space to host the content > indefinitely, then we need to set a fixed, but longer, retention > period before deleting it. Several years, at least. In the mean > time, we could delete builds for intermediate versions (maybe if > we have 10.0.0, 10.1.0, and 10.1.1 we only need to keep 10.1.1, for > example). The point is that there are ways to remove some content > without removing it all. I know space used to be a real problem > when we were hosting on CloudSites, but maybe someone from the infra > team can give us some insight into how significant the space issue > is today? since we publish both versions like 10.0.0 and branches like stable/ocata, i wonder whether we need both, so do we need the tagged documents if we continously publish to branches? 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
Re: [openstack-dev] [docs][release][stable][ptl][infra] Strategic discussion regarding the future of documentation for EOL releases
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 +: >>> 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
Re: [openstack-dev] [docs][release][stable][ptl][infra] Strategic discussion regarding the future of documentation for EOL releases
[snip] > > My proposal is to put the documentation on docs.openstack.org and > leave it there indefinitely. > I like this approach. With the size being manageable (large, but manageable), I would prefer we leave it until we need to free up some of the space. So until that time, no action is required and passively we provide the legacy information for those that need it. Sean __ 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
Re: [openstack-dev] [docs][release][stable][ptl][infra] Strategic discussion regarding the future of documentation for EOL releases
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 +: > > 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
Re: [openstack-dev] [docs][release][stable][ptl][infra] Strategic discussion regarding the future of documentation for EOL releases
Excerpts from Jeremy Stanley's message of 2017-07-27 21:56:35 +: > On 2017-07-27 15:40:22 -0400 (-0400), Doug Hellmann wrote: > [...] > > Regarding point 2, if we don't have the space to host the content > > indefinitely, then we need to set a fixed, but longer, retention > > period before deleting it. Several years, at least. In the mean > > time, we could delete builds for intermediate versions (maybe if > > we have 10.0.0, 10.1.0, and 10.1.1 we only need to keep 10.1.1, for > > example). The point is that there are ways to remove some content > > without removing it all. I know space used to be a real problem > > when we were hosting on CloudSites, but maybe someone from the infra > > team can give us some insight into how significant the space issue > > is today? > [...] > > The current content for all of docs.openstack.org weighs in at > roughly 11GiB on disk. I'm not surprised that was a massive Web site > by CloudSites' standards, but compared to the ~11TiB we host for > just two months of CI job logs it's a 1ml drop in a liter bucket. Excellent, so we don't need to worry about space, for now. 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
Re: [openstack-dev] [docs][release][stable][ptl][infra] Strategic discussion regarding the future of documentation for EOL releases
Excerpts from Jeremy Stanley's message of 2017-07-27 22:07:33 +: > 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 __ 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
Re: [openstack-dev] [docs][release][stable][ptl][infra] Strategic discussion regarding the future of documentation for EOL releases
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. -- Jeremy Stanley signature.asc Description: Digital signature __ 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
Re: [openstack-dev] [docs][release][stable][ptl][infra] Strategic discussion regarding the future of documentation for EOL releases
On 2017-07-27 15:40:22 -0400 (-0400), Doug Hellmann wrote: [...] > Regarding point 2, if we don't have the space to host the content > indefinitely, then we need to set a fixed, but longer, retention > period before deleting it. Several years, at least. In the mean > time, we could delete builds for intermediate versions (maybe if > we have 10.0.0, 10.1.0, and 10.1.1 we only need to keep 10.1.1, for > example). The point is that there are ways to remove some content > without removing it all. I know space used to be a real problem > when we were hosting on CloudSites, but maybe someone from the infra > team can give us some insight into how significant the space issue > is today? [...] The current content for all of docs.openstack.org weighs in at roughly 11GiB on disk. I'm not surprised that was a massive Web site by CloudSites' standards, but compared to the ~11TiB we host for just two months of CI job logs it's a 1ml drop in a liter bucket. -- Jeremy Stanley signature.asc Description: Digital signature __ 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
Re: [openstack-dev] [docs][release][stable][ptl][infra] Strategic discussion regarding the future of documentation for EOL releases
[Moving a thread from the openstack-docs list [1] to this list for broader input.] [1] http://lists.openstack.org/pipermail/openstack-docs/2017-July/010069.html Excerpts from 's message of 2017-07-26 07:42:38 -0400: > Yesterday was a very busy day on IRC, with the discussion about the > strategy and future maintenance of the documentation for the EOL > releases coming back to the front. > > I've promised to summarize some of what we discussed, for those who > weren't there, and sketch out some of the fenceposts along our path forward. > > Summary: > The main issue, is that when an OpenStack release goes EOL, the branch > in the main repository goes away, and with it go the docs, which then > vanish from the public-facing website. > > This has been an open gap for awhile, but only recently became a pain > point for many operators. I think we can all agree that this is an > issue, so the "Why should we fix this?" isn't as important as "HOW do we > fix this?" Yes, as I said on IRC, I think we have reached a point where enough of our user base is trailing far enough behind that we need to rethink our documentation retention policy to make sure we're meeting everyone's needs. > This leaves any sites, operators or installations that may be using > those releases, without any tangible way to research how to install, > manage or maintain those in-place installations and releases. > > For companies like Canonical, we support OpenStack on Ubuntu LTS > releases beyond the upstream EOL date of those point releases > themselves. Other distributions may have a similar gap with the docs > vanishing before their support of those releases sunsets. > > Ideally, docs should be managed and maintained at the upstream project > site, not at each disribution's own domain. I'd like to avoid having a > Canonical version, a Red Hat version, an Oracle version, etc. all with > the same patches to build local copies staged on our respective domains. > > I've recently put some effort into automating and patching off the older > versions of the docs based on the github tags, so they build in a local > tree with mvn/tox, and that tree can be used internally by operators, > but this should be viewed as a stopgap to a more strategic archiving > solution for these docs. > > There is an archiving plan[0] that has been discussed, but with the -doc > team resources being thinned out, there is very little "spare" resources > to put towards this effort. There's been some discussion[1],[2] to try > to bring this to the front, but it too suffers from time and resources. > > There are a few key problems/challenges/questions with solving this in a > repeatable, strategic way: > > * The branches are gone so there's no way to "update" these eol docs, > patch them to build, or maintain them going forward for those eol > releases. > > * Should the eol docs be pulled out and put into their own separate > github repo, where they _can_ be patched and maintained so they > continue to be buildable and usable by those with the correct > tools and environment? > > * There's been talk about pulling the docs into a community- > maintained 'wiki', for ongoing maintenance, but that opens more > questions too (who should host it? who 'owns' it? who gets write > vs. read access? etc.) As Jeremy pointed out on the docs list, this doesn't really help. Moving the content won't give us more maintainers. I don't think we want to enable "maintenance" of the docs as such, though. I think we just want to make them available as they are for users to find. This week we made some progress there, so that now docs.openstack.org has a landing page for every series (for example https://docs.openstack.org/austin/). For the series where docs still existed on the server, we added links. The earliest release with any docs available was Icehouse. We have progressively more material as you look at more recent releases. > * Where should the docs ultimately "live", until they're truly eol for > all parties concerned, and what should that timeline be? 3 years > past eol? 5 years? Indefinitely? > > * We discussed something like: docs.o.o/eol_$release or similar > indicator to differentiate the 'current' docs from the > archived/eol docs. > > * Should the docs for eol releases be made available in PDF only > format, or indexable/searchable HTML format? There are pros and > cons for using either approach, this might need more thought. I think we want to take a "less is more" approach here. When we had lots of contributors working on the docs, it made sense to ask them to do things that I think we can't afford to do any more. So rather than looking for a new way to do something, let's see if we can *stop* doing work and achieve more. My proposal is to put the documentation on docs.openstack.org and leave it there indefinitely. Leaving the docs where they are avoids a ton of work to build archiving systems and f