Re: [openstack-dev] [docs][release][stable][ptl][infra] Strategic discussion regarding the future of documentation for EOL releases

[Tony Breeds]

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

[Doug Hellmann]

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

[Tony Breeds]

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

[Doug Hellmann]

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

[Doug Hellmann]

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

[Jay S Bryant]

+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

[Sean McGinnis]

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

[Jeremy Stanley]

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

[Kevin Benton]

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

[Jeremy Stanley]

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

[David Desrosiers]

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

[David Desrosiers]

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

[Doug Hellmann]

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

[Jeremy Stanley]

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

[Doug Hellmann]

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

[Doug Hellmann]

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

[Dmitry Tantsur]

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

[Thierry Carrez]

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

[Andreas Jaeger]

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

[Andreas Jaeger]

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

[Andreas Jaeger]

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

[Sean McGinnis]

[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

[Doug Hellmann]

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

[Doug Hellmann]

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

[Doug Hellmann]

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

[Jeremy Stanley]

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

[Jeremy Stanley]

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

[Doug Hellmann]

[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