Bug 1521124

Summary:	Hosted engine is referred to as different names within the same documentation
Product:	[Red Hat Storage] Red Hat Gluster Storage	Reporter:	Adam Scerra <ascerra>
Component:	doc-Deploying_RHHI	Assignee:	Laura Bailey <lbailey>
Status:	CLOSED CURRENTRELEASE	QA Contact:	SATHEESARAN <sasundar>
Severity:	medium	Docs Contact:
Priority:	medium
Version:	rhhi-1.1	CC:	asriram, James015Sims, jroberts, khartsoe, lbailey, rhs-bugs, sasundar, seamurph
Target Milestone:	---
Target Release:	RHHI-V 1.6.z Async Update
Hardware:	x86_64
OS:	Linux
Whiteboard:
Fixed In Version:		Doc Type:	If docs needed, set a value
Doc Text:		Story Points:	---
Clone Of:		Environment:
Last Closed:	2019-08-05 06:17:18 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:
Bug Depends On:
Bug Blocks:	1724792, 1723361

Description Adam Scerra 2017-12-05 20:26:27 UTC

Description of problem:
Link to Document: https://access.redhat.com/documentation/en-us/red_hat_hyperconverged_infrastructure/1.0/html/deploying_red_hat_hyperconverged_infrastructure/configure-gluster-rhv-manager#create_the_logical_network_for_gluster_traffic

The Hosted Engine is referred to as "the engine" and "Red Hat Virtualization Manager" throughout the document.

Version-Release number of selected component (if applicable):


How reproducible:
always

Actual results:
Example of Hosted Engine being referred to as different names.

9.1. Create the logical network for gluster traffic
    1. Log in to the engine 
9.3. Add remaining virtualization hosts to the hosted engine.
Follow these steps in Red Hat Virtualization Manager for each of the other hosts. 


Expected results:
Reference to Hosted Engine should be consistent throughout the entire document, or have a note at the beginning of the doc stating that Hosted Engine can be referred to as "Hosted Engine", "Red Hat Virtualization Manager" or "RHV-M".

Additional info:

Comment 2 SATHEESARAN 2017-12-06 04:00:29 UTC

Adam,

Self-Hosted Engine ( SHE ) is a virtualized environment in which RHV Engine runs on a virtual machine on the hosts managed by that engine.

Whenever we refer to the VM itself, we refer it as hosted-engine or engine.
But when referring to the UI, we call it as RHV UI or RHV Manager.

To make it more clear, the application ( RHV Manager ) runs on the VM. This VM is referred as 'hosted engine or engine VM'

Examples.

Hosted-Engine
--------------
Configure hosted engine to something.
hosted-engine runs on host1

RHV UI or RHV Manager
----------------------
Login in to RHV Manager , go to Datacenter tab.


I agree that the doc should stick to one terminology referring to VM and application.

@Laura, we need to look in to 3 different changes
1. Refer all engine & hosted-engine instances in to one term
2. Refer all RHV UI or RHV Manager instances in to one term
3. Make sure engine or RHV UI is referred in exact places. Means, we should not have referred engine in the place of RHV UI. 
Example: 'Login in to Engine' is incorrect, rather than it would be clear to use 'Login in to RHV UI'

Also it would be nice to have the terminology section to avoid such ambiguity.

Comment 3 SATHEESARAN 2017-12-06 04:01:23 UTC

It looks like a lot of changes in the doc, why don't we take it for RHHI 1.0 async doc release ?

Comment 4 Laura Bailey 2017-12-06 04:27:38 UTC

Thanks for the added info, Sas, and thanks for logging this, Adam.

This is something I've been meaning to look at in more detail, as I know we are currently using subtly different terminology to the RHV team.

The definitions that we should be moving toward, based on those used by the RHV team, are included at the bottom of this comment. Based on this, I think we need the following changes for this bug:

1. Change engine, hosted engine, etc. to "self-hosted engine" unless referring to the node, in which case, "self-hosted engine node".
2. Change RHV-M, RHV UI, etc. to "Administration Portal" unless referring to the node, in which case, "self-hosted engine node" or "Red Hat Virtualization Manager" - probably the former, to avoid confusion.
3. Generally, ensure that we are referring to the appropriate thing with the appropriate term.

---

self-hosted engine (noun)

A self-hosted engine is a virtualized environment in which the Manager, or engine, runs on a virtual machine on the hosts managed by that Manager. The virtual machine is created as part of the host configuration, and the Manager is installed and configured in parallel to the host configuration process.

Use all lower case, unless used in a title or at the beginning of a sentence.

Incorrect forms: hosted engine, hosted-engine

---

self-hosted engine node (noun)

A self-hosted engine is a virtualized environment in which the Manager, or engine, runs on a virtual machine on the hosts managed by that Manager. A self-hosted engine node is a host that has self-hosted engine packages installed so that it can host the Manager virtual machine. Regular hosts can also be attached to a self-hosted engine environment, but cannot host the Manager virtual machine.

Use all lower case, unless used in a title or at the beginning of a sentence.

Incorrect forms: hosted engine host, hosted-engine host, self-hosted engine host, hosted engine node, hosted-engine node

---

Administration Portal (noun)

The Administration Portal is a graphical user interface provided by the Red Hat (Enterprise) Virtualization Manager. It can be used to manage all the administrative resources in the environment and can be accessed by any supported web browser.

Always use "Administration Portal", including the capital P. When other departments (or upstream) use "webadmin" or "Administrator portal", this is what they are referring to.

Incorrect forms: Admin Portal, webadmin, webadmin portal, Administrator Portal, Administration portal