Bug 1456897

Summary:	Remove unclear / unneeded options from minor update documentation
Product:	Red Hat OpenStack	Reporter:	Andreas Karis <akaris>
Component:	documentation	Assignee:	Dan Macpherson <dmacpher>
Status:	CLOSED CURRENTRELEASE	QA Contact:	RHOS Documentation Team <rhos-docs>
Severity:	unspecified	Docs Contact:
Priority:	unspecified
Version:	10.0 (Newton)	CC:	akaris, augol, dmacpher, hjensas, mburns, sathlang, srevivo, yroblamo
Target Milestone:	---
Target Release:	---
Hardware:	Unspecified
OS:	Unspecified
Whiteboard:
Fixed In Version:		Doc Type:	If docs needed, set a value
Doc Text:		Story Points:	---
Clone Of:		Environment:
Last Closed:	2017-05-31 16:39:34 UTC	Type:	Bug
Regression:	---	Mount Type:	---
Documentation:	---	CRM:
Verified Versions:		Category:	---
oVirt Team:	---	RHEL 7.3 requirements from Atomic Host:
Cloudforms Team:	---	Target Upstream Version:
Embargoed:

Description Andreas Karis 2017-05-30 15:57:38 UTC

Description of problem:
Remove unclear / unneeded options from documentation

https://access.redhat.com/documentation/en-us/red_hat_openstack_platform/10/html/upgrading_red_hat_openstack_platform/sect-updating_the_environment

~~~
2.3. Updating the Overcloud Packages

The Overcloud relies on standard RPM methods to update the environment. This involves two steps:

    Updating the current plan using your original openstack overcloud deploy command and including the --update-plan-only option. For example:

    $ openstack overcloud deploy --update-plan-only \
      --templates  \
      -e /usr/share/openstack-tripleo-heat-templates/environments/network-isolation.yaml \
      -e /home/stack/templates/network-environment.yaml \
      -e /home/stack/templates/storage-environment.yaml \
      -e /home/stack/templates/rhel-registration/environment-rhel-registration.yaml \
      -e /usr/share/openstack-tripleo-heat-templates/environments/updates/update-from-vip.yaml \
      -e /home/stack/templates/param-updates.yaml
~~~

Specifically, I'm referring to these 2 options:
~~~
      -e /usr/share/openstack-tripleo-heat-templates/environments/updates/update-from-vip.yaml \
      -e /home/stack/templates/param-updates.yaml
~~~

Note that either these are important and need to be explained in the doc, or they should be removed because their presence in combination with their name (`update-from-vip.yaml`, `param-updates.yaml`) is very confusing.

Thanks,

Andreas

Comment 1 Dan Macpherson 2017-05-30 16:49:02 UTC

Hi Andreas,

I've changed the confusing environment files to use an optional in brackets. So the command is now:

$ openstack overcloud deploy --update-plan-only \
  --templates  \
  -e /usr/share/openstack-tripleo-heat-templates/environments/network-isolation.yaml \
  -e /home/stack/templates/network-environment.yaml \
  -e /home/stack/templates/storage-environment.yaml \
  -e /home/stack/templates/rhel-registration/environment-rhel-registration.yaml \
  [OTHER ENVIRONMENT FILES]

I've applied this patch to all previous versions.

Does that suit what you were after?

Comment 2 Andreas Karis 2017-05-30 17:03:52 UTC

Hi,

Yes, that should do it :-)

Thanks!

- Andreas

Comment 3 Dan Macpherson 2017-05-30 17:04:22 UTC

*** Bug 1414262 has been marked as a duplicate of this bug. ***

Comment 4 Dan Macpherson 2017-05-30 17:04:33 UTC

*** Bug 1454710 has been marked as a duplicate of this bug. ***

Comment 5 Dan Macpherson 2017-05-30 17:12:22 UTC

Also checking with Sofer as per duplicate BZs.

Sofer, here are the links to the previous versions:

OSP9: https://access.redhat.com/documentation/en-us/red_hat_openstack_platform/9/html-single/upgrading_red_hat_openstack_platform/#sect-Updating_the_Overcloud

OSP8: https://access.redhat.com/documentation/en-us/red_hat_openstack_platform/8/html-single/upgrading_red_hat_openstack_platform/#sect-Updating_the_Overcloud

How do these look to you? Any further changes required?

Comment 6 Sofer Athlan-Guyot 2017-05-31 13:06:29 UTC

Hi Dan,

the usual expected "man" way is more like [-e <environment_file>|...] but that's just me :)[1]

If It looks good to Andreas that's fine by me.

Thanks,

[1] https://linux.die.net/man/7/man-pages

Comment 7 Andreas Karis 2017-05-31 14:08:55 UTC

[-e <environment_file>|...]     looks good, actually :)

Comment 8 Dan Macpherson 2017-05-31 15:20:17 UTC

Made the switch to the manpage syntax for OSP8 to OSP11. Here's the OSP11 version:

https://access.redhat.com/documentation/en-us/red_hat_openstack_platform/11/html-single/upgrading_red_hat_openstack_platform/#sect-Updating_the_Overcloud

How does it look now, Sofer?

Comment 9 Sofer Athlan-Guyot 2017-05-31 16:27:11 UTC

Hi Dan,

(In reply to Dan Macpherson from comment #8)
> Made the switch to the manpage syntax for OSP8 to OSP11. Here's the OSP11
> version:
> 
> https://access.redhat.com/documentation/en-us/red_hat_openstack_platform/11/
> html-single/upgrading_red_hat_openstack_platform/#sect-Updating_the_Overcloud
> 
> How does it look now, Sofer?

gorgeous :)

Thanks.

Comment 10 Dan Macpherson 2017-05-31 16:39:34 UTC

(In reply to Sofer Athlan-Guyot from comment #9)
> Hi Dan,
> 
> (In reply to Dan Macpherson from comment #8)
> > Made the switch to the manpage syntax for OSP8 to OSP11. Here's the OSP11
> > version:
> > 
> > https://access.redhat.com/documentation/en-us/red_hat_openstack_platform/11/
> > html-single/upgrading_red_hat_openstack_platform/#sect-Updating_the_Overcloud
> > 
> > How does it look now, Sofer?
> 
> gorgeous :)

https://ci.memecdn.com/5475760.jpg

> 
> Thanks.

No prob. Thanks for highlighting this issue!