Note: This is a beta release of Red Hat Bugzilla 5.0. The data contained within is a snapshot of the live data so any changes you make will not be reflected in the production Bugzilla. Also email is disabled so feel free to test any aspect of the site that you want. File any problems you find or give feedback here.
Bug 1080650 - [Docs] [Admin] 13.7. Explanation of Settings and Controls in the Add Provider Window
Summary: [Docs] [Admin] 13.7. Explanation of Settings and Controls in the Add Provider...
Keywords:
Status: CLOSED CURRENTRELEASE
Alias: None
Product: Red Hat Enterprise Virtualization Manager
Classification: Red Hat
Component: Documentation
Version: 3.4.0
Hardware: Unspecified
OS: Unspecified
high
medium
Target Milestone: ---
: 3.5.0
Assignee: Andrew Dahms
QA Contact: Julie
URL:
Whiteboard:
Depends On:
Blocks: RHEV-RHCI
TreeView+ depends on / blocked
 
Reported: 2014-03-25 21:20 UTC by Matt Reid
Modified: 2014-10-29 04:14 UTC (History)
8 users (show)

Fixed In Version:
Doc Type: Bug Fix
Doc Text:
Clone Of:
Environment:
Build Name: 13109, Administration Guide-3.3-1 Build Date: 09-01-2014 15:36:24 Topic ID: 23161-566688 [Latest]
Last Closed: 2014-10-29 04:14:02 UTC
oVirt Team: ---


Attachments (Terms of Use)
Adding Providers Table (deleted)
2014-03-25 21:21 UTC, Matt Reid
no flags Details

Description Matt Reid 2014-03-25 21:20:48 UTC
Title: Add Provider General Settings Explained

Describe the issue: My understanding is that this is a tech preview feature, but the details around configuring an external provider could be more clear.

The definitions are not actually definitions, if you don't already know what a Provider URL is by reading the label: "Provider URL", having the definition be "The URL of the provider" isn't going to help you understand what it is or should look like, or what format it should be entered in. This applies to many of the fields described in this section.


Suggestions for improvement: Provide more context, or examples, or define it using language that doesn't repeat the field label, so that the customer has a greater chance of understanding what we're asking for, and knows how to provide it in a way that RHEV can use. RHEV and OpenStack use a lot of different language, it would be nice if we were more specific here on what to point to. 

Is the provider the Networking Node? The Compute node? Does it matter if it's Neutron Networking? How do I know if I'm using Linux Bridge or Open vSwitch? What's an OpenStack tenant? What's the difference between OpenStack Server vs OpenStack Image? Why would I pick one over the other?

Additional information: It's also worth pointing out that while the docs say the possible Provider types are "Foreman, OpenStack Image, and OpenStack Server", RHEV actually has the following options "Foreman, OpenStack Image, and OpenStack Network". Not all the terms match up between doc and UI here.

Comment 1 Matt Reid 2014-03-25 21:21:41 UTC
Created attachment 878699 [details]
Adding Providers Table

Comment 2 Andrew Dahms 2014-03-27 01:52:18 UTC
Fixed in 23161, 25146, 25098, and 25147.

Comment 3 Andrew Dahms 2014-04-27 03:43:52 UTC
Documentation Link
------------------------------
http://documentation-devel.engineering.redhat.com/site/documentation/en-US/Red_Hat_Enterprise_Virtualization/3.4/html-single/Administration_Guide/index.html#Explanation_of_Settings_and_Controls_in_the_Add_Provider_and_Edit_Provider_Windows

What Changed
------------------------------
The following topics were revised to add further details to each of the settings and clarify their use, along with which passwords and user names must be used to authenticate with each type of external provider.

Add Provider General Settings Explained [23161-624543]

Add Provider Agent Configuration Settings Explained [25146-624549]

Edit Provider General Settings Explained [25098-624544]

Edit Provider Agent Configuration Settings Explained [25147-624548]

Updated revision history: [30102-624554]

NVR
------------------------------
Red_Hat_Enterprise_Virtualization-Administration_Guide-3.4-en-US-3.4-5

Moving to ON_QA.

Comment 4 Jodi Biddle 2014-07-14 15:14:08 UTC
Hi Matt

Can you please provide some QE on this bug and if you think it looks good, change the bug status to verified? Thanks

Comment 5 Matt Reid 2014-07-14 20:47:32 UTC
I'm still not quite sure when one should select Linux Bridge or Open vSwitch. 
In the procedure we say: "Click the text field for Network Plugin and select either Linux Bridge or Open vSwitch in accordance with the plug-in set up in your OpenStack environment."
In the table, we describe it as: "The network plug-in with which to connect to the OpenStack server. Users can select either Linux Bridge or Open vSwitch."

Is it a safe assumption that users will know which to select? I don't think I would from those descriptions. Does one relate back to Neutron and the other to Nova?


Minor, but if we're saying the field is "Username", in the description of it, we probably should keep it as one word, we switch to "user name" there.

Some of the service/server instances may need to be prefixed by a "the".

For example:
"Username: A user name for connecting to OpenStack Image Service. This user name must be the user name for OpenStack Image Service registered in the Keystone instance of which the OpenStack Image Service instance is a member. By default, this user name is glance."

Some of the times things like "OpenStack Image Service" are mentioned, we say "the OpenStack Image Service", and other times we don't. Some of the times we don't sound a little awkward to me (like in the above example).

Overall though, these are much more descriptive and I would think people reading the docs would know what they're being asked for, if it wasn't obvious to them from the dialog.

Comment 6 Andrew Dahms 2014-09-02 02:05:43 UTC
Hi Matt,

Thank you for your feedback, and my sincere apologies for the delay in getting back to you.

To address your concerns, I have made the following changes -

* I have used the same wording in the settings table as used in the procedure with regard to the Linux Bridge and Open vSwitch. In regards to which is appropriate, when users set up the OpenStack components to act as external providers, they must set up a plug-in as outlined in the OpenStack documentation, and specify the type of plug-in they set up here. By way of helping users find the right information, I have added a 'note' box to "Introduction to External Providers in Red Hat Enterprise Virtualization" to clarify that users must set up the components first, including a link to related documentation on the OpenStack side. I will also follow up with the OpenStack documentation and see if further information can be added on that side as well.

* I have now added 'the' to the instances of the service names in the tables.

* I also agree with you in that 'username' and 'user name' should match. At current, our overall standard is to use 'user name' as two distinct words, which is in conflict with the user interface element here 'username'. If possible, I would be inclined to use 'user name' to follow our overall standard here, and will see if I can submit a patch against the user interface to change 'username' to 'user name' so that the two match.

You can find the changes here:
http://docbuilder.usersys.redhat.com/22720/#Introduction_to_Third_Party_Resource_Providers_in_Red_Hat_Enterprise_Virtualization

Please let me know if you have any further feedback.

Kind regards,

Andrew

Comment 7 Julie 2014-09-02 13:39:08 UTC
Verified in the 3.4 guide. The content will be available in the next async release.

Comment 8 Deon Ballard 2014-09-02 14:19:09 UTC
Andrew,

We should always have the docs reflect what is in the UI, regardless of any other standards. (The only exception is a real typo, like if it were "uesr name" or something.)

Comment 9 Andrew Dahms 2014-09-03 07:06:15 UTC
Hi Deon,

Thank you for your feedback.

I have now updated the documentation to use 'username' in all places in the relevant topics, and have given the same treatment to 'plug-in' as well.

Please let me know if Matt or yourself have any further feedback or concerns.

Kind regards,

Andrew

Comment 10 Andrew Dahms 2014-09-23 22:09:52 UTC
Documentation Link
------------------------------
https://documentation-devel.engineering.redhat.com/site/documentation/en-US/Red_Hat_Enterprise_Virtualization/3.4/html-single/Administration_Guide/index.html#chap-External_Providers

What Changed
------------------------------
The following topics were revised to add further details to each of the settings and clarify their use, along with which passwords and user names must be used to authenticate with each type of external provider. Furthermore,  the topics on settings for editing external provider settings have been removed, and a 'Note' box was added to the introductory topic to help point users towards documentation that will assist in setting up a RHEL-OSP environment and identifying several of the key values required to add providers.

Introduction to External Providers in Red Hat Enterprise Virtualization [23158-705627]

Add Provider General Settings Explained [23161-706017]

Add Provider Agent Configuration Settings Explained [25146-705970]

Updated revision history: [30102-624554]

NVR
------------------------------
Red_Hat_Enterprise_Virtualization-Administration_Guide-3.4-en-US-3.4-33.0

Moving to ON_QA.

Comment 11 Julie 2014-10-07 02:40:13 UTC
Reviewed for the additional changes. Moving to Verified. Once published, move this bug to Closed-current release.


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