Bug 1025757 - redundant content [NEEDINFO]
redundant content
Status: ASSIGNED
Product: Red Hat Enterprise MRG
Classification: Red Hat
Component: Messaging_Programming_Reference (Show other bugs)
Development
Unspecified Unspecified
unspecified Severity low
: ---
: ---
Assigned To: mmurray
Petr Matousek
: Documentation
Depends On:
Blocks: 1032609
  Show dependency treegraph
 
Reported: 2013-11-01 09:25 EDT by Petr Matousek
Modified: 2017-04-20 21:26 EDT (History)
5 users (show)

See Also:
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: ---
zkraus: needinfo? (smumford)


Attachments (Terms of Use)

  None (edit)
Description Petr Matousek 2013-11-01 09:25:48 EDT
Description of problem:

1.) In the chapters below the hello world examples are listed for supported client's languages:
3.1.5. Perl "Hello World" Program Listing
3.2.5. Python "Hello World" Program Listing
3.3.7. .NET C# "Hello World" Program Listing
3.4.3.6. C++ "Hello World" Program Listing

The same examples are listed again in the following chapter (for all the supported languages)
3.7.1. Red Hat Enterprise Messaging "Hello World"

I believe this redundant content is not necessary and I suggest to remove the above mentioned examples and keep only the - 3.7.1. Red Hat Enterprise Messaging "Hello World" section


2.) The same content is listed for Message groups in the MPR and the MCIG.

6.8. Message Groups (MPR)
4.7. Message Groups (MCIG)

As above, I believe that it's enough to document this either in MPR(preferably) or in MCIG.

Version-Release number of selected component (if applicable):
Messaging Programming Reference - Revision 0.0.0-9

How reproducible:
n/a

Steps to Reproduce:
n/a

Actual results:
redundant content

Expected results:
duplicates removed

Additional info:
Comment 2 Petr Matousek 2013-11-20 08:15:53 EST
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
Comment 3 Joshua Wulf 2014-06-23 23:02:35 EDT
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?
Comment 4 Valiantsina Hubeika 2014-07-15 08:29:44 EDT
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'
Comment 5 Joshua Wulf 2014-08-06 22:31:15 EDT
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
Comment 7 Valiantsina Hubeika 2014-08-21 07:12:46 EDT
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"'
Comment 8 Joshua Wulf 2014-08-21 19:41:48 EDT
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.
Comment 11 Petr Matousek 2014-08-27 11:48:13 EDT
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).
Comment 13 Jared MORGAN 2014-12-22 19:31:05 EST
(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
Comment 14 Petr Matousek 2015-01-05 12:05:06 EST
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.
Comment 16 Jared MORGAN 2015-06-15 01:43:59 EDT
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. ;)
Comment 18 Jared MORGAN 2015-07-09 23:38:18 EDT
(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/
Comment 21 Scott Mumford 2015-09-02 20:46:01 EDT
Taking ownership of MRG-M bugs
Comment 25 Petr Matousek 2015-10-07 11:36:43 EDT
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

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