Bug 1536125

Summary: RHHI-V deploy and configuration usability is hard to consume by the end user
Product: [Red Hat Storage] Red Hat Gluster Storage Reporter: Dave <dfitzpat>
Component: doc-Deploying_RHHIAssignee: Laura Bailey <lbailey>
Status: CLOSED CURRENTRELEASE QA Contact: SATHEESARAN <sasundar>
Severity: high Docs Contact:
Priority: high    
Version: rhhi-1.1CC: annair, ascerra, asriram, jroberts, khartsoe, lbailey, rhs-bugs, sabose, ygoitom
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:10 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, 1536128, 1723361    

Description Dave 2018-01-18 16:36:51 UTC 
Description of problem:
There's no one document for setting up RH-HI right now (or a simple, easy to consume, automated approach either). There's 4+ documents to follow. This lends itself to deterring the end user from setting up and using this product at all. This severely inhibits the user experience in addition to inhibiting testing internally by Red Hat engineers. It is a daily task to figure out what we're trying to do at a concept level versus how that translates into RHV-m versus how to actually do that via the gui and/or cli. This should all be a seamless experience. Left unchanged this will hurt the RH-HI solutions acceptance.

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

How reproducible:
Daily issues


Expected results:

An easy to follow document (Read: One document) that clearly has the steps to manually deploy & configure a RH-HI POD
Comment 2 Laura Bailey 2018-03-14 10:28:44 UTC 
Resetting component as this looks like it's primarily a docs issue.
Comment 4 Dave 2018-07-03 13:51:24 UTC 
Adding more context as the CS&S is going through our notes.

Question:
Is there a new documentation tool still being considered?

Issue:
In multi-page html & pdf versions of documentation "Deploy" and all headers of PARTs appear as blank pages and lead to a messy/unpolished document.

Doc in Question:
https://access.redhat.com/documentation/en-us/red_hat_hyperconverged_infrastructure/1.1/html/deploying_red_hat_hyperconverged_infrastructure/deploy

Proposed solutions:
#1 Incorporate something else on the page. a table of contents of that section or a "this page was intentionally left blank" disclaimer
#2 If the new tool is still on the road map and would take care of this than that is a reasonable solution too.
Comment 5 Laura Bailey 2018-07-05 03:04:37 UTC 
Thanks for the extra context here Dave.

The blank page issue isn't something the docs writers can fix directly, since as you mention it does involve tooling beyond the markup language that we write in. I believe those blanks are in place so that printing for binding purposes is accounted for (starting chapters on the right-hand page, etc.) but you're right that the blanks in the HTML view are confusing.

I'll touch base with the tools team and the content strategist to see what we can do about altering these things.
Comment 6 Laura Bailey 2018-07-06 01:38:15 UTC 
Just letting you know that discussion is happening and we're pretty sure it's an interpretation-by-the-backend thing that has the front-end workaround of 'add some superfluous content here so it's not confusingly blank' right now. We're working on a less superfluous option.
Comment 7 Laura Bailey 2018-10-24 07:20:57 UTC 
Ongoing discussion, postponing.
Comment 20 SATHEESARAN 2019-07-24 13:03:30 UTC 
The doc changes looks good and unambiguous. Most of the sections have that added clarity