Bug 1025757
Summary: | redundant content | |||
---|---|---|---|---|
Product: | Red Hat Enterprise MRG | Reporter: | Petr Matousek <pematous> | |
Component: | Messaging_Programming_Reference | Assignee: | Nobody <nobody> | |
Status: | ASSIGNED --- | QA Contact: | Petr Matousek <pematous> | |
Severity: | low | Docs Contact: | ||
Priority: | unspecified | |||
Version: | Development | CC: | messaging-qe-bugs, pematous, zkraus | |
Target Milestone: | --- | Keywords: | Documentation | |
Target Release: | --- | Flags: | zkraus:
needinfo?
(smumford) |
|
Hardware: | Unspecified | |||
OS: | Unspecified | |||
Whiteboard: | ||||
Fixed In Version: | 984017 957948 | Doc Type: | Bug Fix | |
Doc Text: | Story Points: | --- | ||
Clone Of: | ||||
: | 1032609 (view as bug list) | Environment: |
MPR: Resolve outstanding issues in Comment#4 and Comment#11.
|
|
Last Closed: | 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: | 1032609 |
Description
Petr Matousek
2013-11-01 13:25:48 UTC
1.) redundant Perl, Python, .NET and C++ examples were removed as expected, but now we end with situation that we have all the above mentioned hello world examples in chapter "3.7. Hello World" and the java hello world example in the "3.5.4. Java JMS "Hello World" Program Listing". I believe it would make sense to consolidate also the java example to the chapter 3.7 and remove the chapter 3.5.4. 2.) The message groups redundant content was removed from MPR and remained in MCIG. Again, I believe that placing the message groups description to MPR is much more appropriate than to MCIG. The message groups functionality is not related to qpidd installation/configuration. What is your opinion? If you'd like I may create a new bugzilla for MCIG for this issue. I'm also cloning this bz for MRG2.x I've moved the Java example to the same chapter as the Hello World examples. For Message Groups, I have this: MCIG content: http://deathstar1.usersys.redhat.com:3000/builds/18173-Messaging_Installation_and_Configuration_Guide/#sect-Message_Groups MPR content: http://deathstar1.usersys.redhat.com:3000/builds/19948-Messaging_Programming_Reference/#sect-Message_Groups I've included background information on Message Groups in both places to give context to the instructions. In the MCIG I have qpid-config related information, and the MPR I've put programming-related information. The rationale there was that qpid-config is used for configuring queues, and I considered configuring queues to be part of "configuration". Does that make sense? Hi Joshua, could you please re-check the last change as it looks like: 1. Java example is still separated from the rest of the Hello World examples: '3.4.4. Java JMS "Hello World" Program Listing' vs '3.6.1. Red Hat Enterprise Messaging "Hello World"' 2. With messages groups its a bit complicated now: I. MICG looks good to me II. MPR has duplicated chapters in itself: '6.8.2. Create a Queue with Message Groups enabled' and ' 6.8.5. Create a Queue with Message Groups enabled' III. MPR still contains duplicated chapters with MICG like: '6.8.4. Configure a Queue for Message Groups using qpid-config', '6.8.6. Default Group', '6.8.7. Override the Default Group Name' I've removed the duplicated section in the MPR. The content duplicated between the two guides is done in order to put relevant information where the reader needs it. It is written once and then included in both books. The idea is to reduce the number of times we refer readers to another book, since hyperlinking between books is not supported. http://deathstar1.usersys.redhat.com:3000/builds/19948-Messaging_Programming_Reference/#sect-Message_Groups Hi Jushua, could you please check this again: MPR: 1. Java example is still separated from the rest of the Hello World examples: '3.4.4. Java JMS "Hello World" Program Listing' vs '3.6.1. Red Hat Enterprise Messaging "Hello World"' Not changing this at this point of the release. The Java Hello World program differs significantly from the other languages. It's object-oriented, and uses a JNDI configuration. So it doesn't lend itself to same inline description that the others share. Merging it with the others in a way that does not complicate the explanation for the others is not a trivial task. This structural issue can be revisited for a future release. I believe that another redundant content is listed in the description of "Subscribe to a XXX Exchange" for Direct/Fanout/Topic exchanges. The difference in pub-sub and shared subscription may be generalized for all the exchanges and the redundant content may be removed. Currently the difference is described using different wording in each of these chapters which is very confusing for the reader. (mixing terms with the same meaning: publisher-subscriber pattern/Copy of messages/ephemeral/private subscription, Move of messages/shared subscription). (In reply to Petr Matousek from comment #11) > I believe that another redundant content is listed in the description of > "Subscribe to a XXX Exchange" for Direct/Fanout/Topic exchanges. > > The difference in pub-sub and shared subscription may be generalized for all > the exchanges and the redundant content may be removed. Currently the > difference is described using different wording in each of these chapters > which is very confusing for the reader. (mixing terms with the same meaning: > publisher-subscriber pattern/Copy of messages/ephemeral/private > subscription, Move of messages/shared subscription). Hey there Petr I have to say I'm having a bit of a hard time following what Josh has done here. From your perspective, what needs to happen from the docs perspective? Since Josh wrote Comment#5, we do have better inter-book linking opportunities. So if you believe this approach was a limiting factor in the way the issue was resolved, we can fix this. Let me know (outside this bug if you prefer) the way you feel this issue would best be resolved, and we can wrap it up for 3.1.0. Cheers J Hi Jared, this bug is generally about removing all the redundant content from our guides. IMHO there is no need to have redundant content in our guides and if there is a possibility to have inter-book links it might be a good solution. Remaining issues to be resolved here (by quick check): comment 4, comment 11. My suggestion is to try to do the best you can with the redundant content and then move this bug to ON_QA, after that I'll look more closely on the changes done. Feel free to contact me with concrete question/issues. Will do this for 3.2: it's been hanging around for too long. (In reply to vhubeika from comment #4) > Hi Joshua, could you please re-check the last change as it looks like: > > 1. Java example is still separated from the rest of the Hello World examples: > '3.4.4. Java JMS "Hello World" Program Listing' vs '3.6.1. Red Hat > Enterprise Messaging "Hello World"' > > 2. With messages groups its a bit complicated now: > I. MICG looks good to me > II. MPR has duplicated chapters in itself: > '6.8.2. Create a Queue with Message Groups enabled' and ' 6.8.5. Create > a Queue with Message Groups enabled' > III. MPR still contains duplicated chapters with MICG like: '6.8.4. > Configure a Queue for Message Groups using qpid-config', '6.8.6. Default > Group', '6.8.7. Override the Default Group Name' Looks like I need to change some PressGang anchors in the MPR. Will do some referential linking adjustments to see if that improves the issue. (In reply to Petr Matousek from comment #11) > I believe that another redundant content is listed in the description of > "Subscribe to a XXX Exchange" for Direct/Fanout/Topic exchanges. > > The difference in pub-sub and shared subscription may be generalized for all > the exchanges and the redundant content may be removed. Currently the > difference is described using different wording in each of these chapters > which is very confusing for the reader. (mixing terms with the same meaning: > publisher-subscriber pattern/Copy of messages/ephemeral/private > subscription, Move of messages/shared subscription). What procedure has the best Subscribe info in your opinion, Petr? I'd like to use only the best. ;) (In reply to vhubeika from comment #4) > Hi Joshua, could you please re-check the last change as it looks like: > > 1. Java example is still separated from the rest of the Hello World examples: > '3.4.4. Java JMS "Hello World" Program Listing' vs '3.6.1. Red Hat > Enterprise Messaging "Hello World"' > > 2. With messages groups its a bit complicated now: > I. MICG looks good to me > II. MPR has duplicated chapters in itself: > '6.8.2. Create a Queue with Message Groups enabled' and ' 6.8.5. Create > a Queue with Message Groups enabled' > III. MPR still contains duplicated chapters with MICG like: '6.8.4. > Configure a Queue for Message Groups using qpid-config', '6.8.6. Default > Group', '6.8.7. Override the Default Group Name' I have moved the sections closer together in Point 1, and linked from Java Client Libraries to the Hello World Java example (just to help users find it if interested). All the points in Point 2 have been covered already and do not exist in http://docbuilder.usersys.redhat.com/19948/ Taking ownership of MRG-M bugs Found another redundant content, that shall be removed: MCIG: 4.4. Exclusive Queues, 4.5. Ignore Locally Published Messages MPR: 6.3. Exclusive Queues, 6.2. Ignore Locally Published Messages |