Description of problem: 5.2.1. Requirements for Provisioning a Host in the Quick Start Guide has an italic "link", rather than an actual hyperlink to the section it references, like some other cross referenced sections in the document. There's another one in 5.1.7. Refreshing Providers, and a few in the note immediately before that section. I'm not sure how many there are, but it doesn't seem like we should have some that are actual links, and others that are just italic text, but don't link. Other sections, such as 5.1.1. Adding a Provider uses hyperlinks to directly link to the referenced sections within the doc, which is much more useful in my opinion, rather than putting the onus on the reader to go find whatever section we mention could be useful.
Created attachment 959395 [details] Italic text for reference to different section of doc
Created attachment 959396 [details] Actual link for reference to different section of doc
Hi Matt, I have added links to all the referenced sections. Link: http://docbuilder.usersys.redhat.com/22847/ Also checked in: Installing CloudForms on Red Hat Enterprise Virtualization Installing CloudForms on Red Hat OpenStack Platform Installing CloudForms on VMware vSphere Management Engine 5.3 Control Guide Management Engine 5.3 Insight Guide Management Engine 5.3 Integration Services Guide Management Engine 5.3 Lifecycle and Automation Guide Management Engine 5.3 Methods Available for Automation Management Engine 5.3 NetApp Storage Integration Guide Management Engine 5.3 OpenShift Enterprise Deployment Guide Management Engine 5.3 Planning Guide Management Engine 5.3 Release Notes Management Engine 5.3 Settings and Operations Guide Management Engine 5.3 Technical Notes Management Engine 5.3 User Guide Please let me know if you find any instances of italic text that should be hyperlinks. Regards, Shikha
I know this bug was originally filed against the 5.3 docs, but "grep 'citetitle' *.xml" for the 5.4-Beta docs gives several instances without links which are in both versions. Let's update the Beta docs and backport where possible. Links to books should be in <ulink> tags without <citetitle>. Xrefs within a book, such as the one mentioned by Matt in 5.2.1, should be handled by PressGang's [[Inject]] syntax without <citetitle>. Links to the Customer Portal will change with the 5.4 GA. For now use links to the 5.3 docs. I will file a separate bug to update these links for the 5.4 GA docs. Also: s/refer to/see s/see the/see etc.
Hi Brian, I have changed all the instances, that were preceding a link, of "refer/refer to/ see the" to "see" in the 3.2 Beta User Guide. I have also fixed the broken links in the User Guide. I have checked the other guides in the 3.2 Beta suite for broken links and fixed them. So far, most of the updates are only applicable to the 3.2 beta docs. Kindly review the 3.2 docs. I will repeat this exercise for the 5.4 docs, please file the bug for 5.4 GA. Regards, Shikha
Assigning to Suyog for peer review.
Verified in all 3.2 books - looks good. Shikha, as discussed can you please make the following two references (in Note) consistent with other references/links in the books: 1. http://docbuilder.usersys.redhat.com/23039/#Adding_a_Red_Hat_Enterprise_Virtualization_Manager_Provider "For information on setting up the Data Warehouse service on the Manager, see the Red Hat Enterprise Virtualization Installation Guide." (Example: http://docbuilder.usersys.redhat.com/23035/#Running_CloudForms_Management_Engine) 2. http://docbuilder.usersys.redhat.com/23046/#chap-Enabling_Public_AMIs_from_Amazon_EC2 "For information on other parameters, see "Configuration Parameters" in the Settings and Operations Guide. " Thanks!
Hi Suyog, The reason for external links being present here was that we decided that if the link is to a specific procedure, it's okay to have the <ulink> tags. But, if the link is to give out more information in another book, then it has to be within <citetitle>. To verify the correct procedure for cross referencing, I referred the style guide, https://obriend.fedorapeople.org/WritingStyleGuide/#chap-Style_Guide-Writing_Style_Guide-Cross_References and it says, "A cross-reference should always point to additional information, not core information that the reader needs to perform the task at hand. For example, in a procedure to configure an application, do not merely provide a link to the appendix where the correct naming conventions are described. Give the reader examples and explanations of a valid file name, and at the end of the procedure provide the link to the appendix." So now, I have 2 options regarding this sort of situation: Option 1: Re-write the procedures that link to other procedures to eliminate the need for deep linking. Option 2: Style guide should be updated to accommodate cross-product guides, in which case deep linking within the cross product documentation should be allowed, even within procedures. I am currently following up with Andrew Dahms on the style guide guidelines to resolve this issue. Regards, Shikha
Hi Shikha, Suyog, For these two references, I am happy for us to use citetitle references for now as long as we follow the format of '"Section Name" in <citetitle>Guide Name</citetitle>'. The reason for this is that there will be some changes to the format of the guides in the RHEV documentation suite in the next release, and there is a possibility that links could be broken across versions, whereas references may provide a slightly more robust method of pointing users to the required information. Let me know if you have any questions or concerns. Kind regards, Andrew
All required changes and feedback has been incorporated in the documentation.
The requested change is now live on the Customer Portal. Closing.