Bug 1276449 - chapter Getting Started (with gdeploy) is too complicated without pointing out all requirements
chapter Getting Started (with gdeploy) is too complicated without pointing ou...
Status: CLOSED CURRENTRELEASE
Product: Red Hat Gluster Storage
Classification: Red Hat
Component: doc-Administration_Guide (Show other bugs)
3.1
Unspecified Unspecified
unspecified Severity low
: ---
: RHGS 3.1.2
Assigned To: Divya
Anush Shetty
: Documentation, ZStream
Depends On:
Blocks:
  Show dependency treegraph
 
Reported: 2015-10-29 14:07 EDT by Martin Bukatovic
Modified: 2017-11-17 00:26 EST (History)
11 users (show)

See Also:
Fixed In Version:
Doc Type: Bug Fix
Doc Text:
Story Points: ---
Clone Of:
Environment:
Last Closed:
Type: Bug
Regression: ---
Mount Type: ---
Documentation: ---
CRM:
Verified Versions:
Category: ---
oVirt Team: ---
RHEL 7.3 requirements from Atomic Host:
Cloudforms Team: ---


Attachments (Terms of Use)

  None (edit)
Description Martin Bukatovic 2015-10-29 14:07:12 EDT
Document URL
============

https://access.redhat.com/documentation/en-US/Red_Hat_Storage/3.1/html/Administration_Guide/chap-Red_Hat_Storage_Volumes.html#chap-Red_Hat_Storage_Volumes-gdeploy

Section Number and Name
=======================

Red Hat Gluster Storage 3.1 - Administration Guide
Chapter 6. Red Hat Gluster Storage Volumes
Section 6.1.1. Getting Started 

Describe the issue
==================

Section "Getting Started" contains *unnecessary complicated* description of
gdeploy package name. On the other hand, the full list of channels required
for gdeploy is not directly mentioned anywhere.

See affected part of the section and my comments inline:

> Using a node in a cluster
> 
> The gdeploy package, is bundled as part of the initial installation of Red Hat
> Gluster Storage:
> 
>     For Red Hat Enterprise Linux 6: gdeploy-1.0-11.el6rhs
>     For Red Hat Enterprise Linux 7: gdeploy-1.0-11.el7rhgs 

While this *was technically correct* statement when the section was created,
there are multiple issues with using almost complete package name including
version, release and distribution version:

 * there is no need to refer to the full version of package
 * moreover doing this for both RHEL 6 and RHEL 7 at the same time looks as if
   there were some subtle difference between the two, which is not the case
   (one can install gdeploy on both rhel 6 and 7 just by running
   'yum install gdeploy' if the machine is subscribed in required channels)
 * it creates unnecessary overhead for the doc team, which is forced to
   update full version of the package each time we release new version
   (see next point)
 * it's not true anymore: we have released more recent build
   of gdeploy tool (1.0-12.el6rhs)

> Using a machine outside the trusted storage pool
> 
> You must ensure that the Red Hat Gluster Storage is subscribed to the required
> channels. For more information see, Subscribing to the Red Hat Gluster Storage
> Server Channels in the Red Hat Gluster Storage 3.1 Installation Guide.
> 
> Execute the following command to install gdeploy:
> 
>     # yum install gdeploy*

Running 'yum install gdeploy*' is not necessary.

You should point to chapter: "2.8. Installing Ansible to Support Gdeploy" of
Installation Guide as well.

Suggestions for improvement
===========================

Simplify the description while providing useful information:

 * stating that package is called gdeploy is clear enough
 * in the example, use 'yum install gdeploy' instead
 * link to the Installing Ansible to Support Gdeploy section
Comment 2 Anjana Suparna Sriram 2015-10-30 05:06:14 EDT
Sac,

Could you review this bug and let us know the changes required?
Comment 3 Sachidananda Urs 2015-10-30 12:37:47 EDT
(In reply to Martin Bukatovic from comment #0)
> Document URL
> ============
> 
> https://access.redhat.com/documentation/en-US/Red_Hat_Storage/3.1/html/
> Administration_Guide/chap-Red_Hat_Storage_Volumes.html#chap-
> Red_Hat_Storage_Volumes-gdeploy
> 
> Section Number and Name
> =======================
> 
> Red Hat Gluster Storage 3.1 - Administration Guide
> Chapter 6. Red Hat Gluster Storage Volumes
> Section 6.1.1. Getting Started 
> 
> Describe the issue
> ==================
> 
> Section "Getting Started" contains *unnecessary complicated* description of
> gdeploy package name. On the other hand, the full list of channels required
> for gdeploy is not directly mentioned anywhere.
> 
> See affected part of the section and my comments inline:
> 
> > Using a node in a cluster
> > 
> > The gdeploy package, is bundled as part of the initial installation of Red Hat
> > Gluster Storage:
> > 
> >     For Red Hat Enterprise Linux 6: gdeploy-1.0-11.el6rhs
> >     For Red Hat Enterprise Linux 7: gdeploy-1.0-11.el7rhgs 
> 
> While this *was technically correct* statement when the section was created,
> there are multiple issues with using almost complete package name including
> version, release and distribution version:
> 
>  * there is no need to refer to the full version of package
>  * moreover doing this for both RHEL 6 and RHEL 7 at the same time looks as
> if
>    there were some subtle difference between the two, which is not the case
>    (one can install gdeploy on both rhel 6 and 7 just by running
>    'yum install gdeploy' if the machine is subscribed in required channels)
>  * it creates unnecessary overhead for the doc team, which is forced to
>    update full version of the package each time we release new version
>    (see next point)
>  * it's not true anymore: we have released more recent build
>    of gdeploy tool (1.0-12.el6rhs)
> 
> > Using a machine outside the trusted storage pool
> > 
> > You must ensure that the Red Hat Gluster Storage is subscribed to the required
> > channels. For more information see, Subscribing to the Red Hat Gluster Storage
> > Server Channels in the Red Hat Gluster Storage 3.1 Installation Guide.
> > 
> > Execute the following command to install gdeploy:
> > 
> >     # yum install gdeploy*
> 
> Running 'yum install gdeploy*' is not necessary.
> 
> You should point to chapter: "2.8. Installing Ansible to Support Gdeploy" of
> Installation Guide as well.
> 
> Suggestions for improvement
> ===========================
> 
> Simplify the description while providing useful information:
> 
>  * stating that package is called gdeploy is clear enough
>  * in the example, use 'yum install gdeploy' instead
>  * link to the Installing Ansible to Support Gdeploy section

Agree with all the points. Will work with documentation team to get these fixed.
Comment 4 Sachidananda Urs 2015-11-01 20:35:47 EST
(In reply to Anjana Suparna Sriram from comment #2)
> Sac,
> 
> Could you review this bug and let us know the changes required?

Anjana, I will co-ordinate with the team to get this resolved ASAP.
Comment 5 Anjana Suparna Sriram 2015-11-02 03:19:20 EST
Will be resolved as part of 3.1.2 release
Comment 9 Divya 2015-11-18 23:06:18 EST
(In reply to Martin Bukatovic from comment #0)
> Document URL
> ============
> 
> https://access.redhat.com/documentation/en-US/Red_Hat_Storage/3.1/html/
> Administration_Guide/chap-Red_Hat_Storage_Volumes.html#chap-
> Red_Hat_Storage_Volumes-gdeploy
> 
> Section Number and Name
> =======================
> 
> Red Hat Gluster Storage 3.1 - Administration Guide
> Chapter 6. Red Hat Gluster Storage Volumes
> Section 6.1.1. Getting Started 
> 
> Describe the issue
> ==================
> 
> Section "Getting Started" contains *unnecessary complicated* description of
> gdeploy package name. On the other hand, the full list of channels required
> for gdeploy is not directly mentioned anywhere.
> 
> See affected part of the section and my comments inline:
> 
> > Using a node in a cluster
> > 
> > The gdeploy package, is bundled as part of the initial installation of Red Hat
> > Gluster Storage:
> > 
> >     For Red Hat Enterprise Linux 6: gdeploy-1.0-11.el6rhs
> >     For Red Hat Enterprise Linux 7: gdeploy-1.0-11.el7rhgs 
> 
> While this *was technically correct* statement when the section was created,
> there are multiple issues with using almost complete package name including
> version, release and distribution version:
> 
>  * there is no need to refer to the full version of package
>  * moreover doing this for both RHEL 6 and RHEL 7 at the same time looks as
> if
>    there were some subtle difference between the two, which is not the case
>    (one can install gdeploy on both rhel 6 and 7 just by running
>    'yum install gdeploy' if the machine is subscribed in required channels)
>  * it creates unnecessary overhead for the doc team, which is forced to
>    update full version of the package each time we release new version
>    (see next point)
>  * it's not true anymore: we have released more recent build
>    of gdeploy tool (1.0-12.el6rhs)

Deleted the version numbers in the package name.

> 
> > Using a machine outside the trusted storage pool
> > 
> > You must ensure that the Red Hat Gluster Storage is subscribed to the required
> > channels. For more information see, Subscribing to the Red Hat Gluster Storage
> > Server Channels in the Red Hat Gluster Storage 3.1 Installation Guide.
> > 
> > Execute the following command to install gdeploy:
> > 
> >     # yum install gdeploy*
> 
> Running 'yum install gdeploy*' is not necessary.

Updated the command as " # yum install gdeploy"

> 
> You should point to chapter: "2.8. Installing Ansible to Support Gdeploy" of
> Installation Guide as well.
> 
> Suggestions for improvement
> ===========================
> 
> Simplify the description while providing useful information:
> 
>  * stating that package is called gdeploy is clear enough
>  * in the example, use 'yum install gdeploy' instead
>  * link to the Installing Ansible to Support Gdeploy section

I have added reference to the Installing Ansible to Support Gdeploy section of the Installation Guide.

Link to the latest guide: http://jenkinscat.gsslab.pnq.redhat.com:8080/job/doc-Red_Hat_Gluster_Storage-3.1-Administration_Guide%20%28html-single%29/lastStableBuild/artifact/tmp/en-US/html-single/index.html#chap-Red_Hat_Storage_Volumes-gdeploy

Moving the bug to ON_QA.
Comment 10 Anush Shetty 2015-12-02 03:58:54 EST
Moving this to verified.

Note You need to log in before you can comment on or make changes to this bug.