Bug 829988 - QE Feedback - Getting Started Guide - Chapter 6
QE Feedback - Getting Started Guide - Chapter 6
Status: CLOSED CURRENTRELEASE
Product: JBoss Data Grid 6
Classification: JBoss
Component: Documentation (Show other bugs)
6.0.0
Unspecified Unspecified
unspecified Severity medium
: ---
: ---
Assigned To: Misha H. Ali
:
Depends On:
Blocks:
  Show dependency treegraph
 
Reported: 2012-06-07 19:05 EDT by Misha H. Ali
Modified: 2012-08-15 10:44 EDT (History)
2 users (show)

See Also:
Fixed In Version:
Doc Type: Bug Fix
Doc Text:
Story Points: ---
Clone Of:
Environment:
Last Closed: 2012-06-14 23:06:30 EDT
Type: Bug
Regression: ---
Mount Type: ---
Documentation: ---
CRM:
Verified Versions:
Category: ---
oVirt Team: ---
RHEL 7.3 requirements from Atomic Host:
Cloudforms Team: ---


Attachments (Terms of Use)

  None (edit)
Description Misha H. Ali 2012-06-07 19:05:51 EDT
* http://documentation-stage.bne.redhat.com/docs/en-US/JBoss_Data_Grid/6/html/Getting_Started_Guide/chap-Run_JBoss_Data_Grid_as_an_Embedded_Cache.html

Topics in this chapter look quite good individually but when I read them together, I'm telling myself that they do not have much
in common. And topic "6.1. Run JBoss Data Grid on a Single Node" says "To run JBoss Data Grid on a single node, perform the following operations: ",
but they are not related. Furthermore, we cannot say "Run JBoss Data Grid using the standalone.sh " when the title of this chapter says
"Run JBoss Data Grid as an Embedded Cache". 

My proposal is to completely remove this topic 6.1 as it is very confusing, or replace it with different topic saying that following
topics should not be considered as related to each other.


* http://documentation-stage.bne.redhat.com/docs/en-US/JBoss_Data_Grid/6/html/Getting_Started_Guide/Add_a_Profile_to_Your_Project.html
* http://documentation-stage.bne.redhat.com/docs/en-US/JBoss_Data_Grid/6/html/Getting_Started_Guide/Maven_Repository_Configuration_Example.html
* http://documentation-stage.bne.redhat.com/docs/en-US/JBoss_Data_Grid/6/html/Getting_Started_Guide/chap-Create_a_New_JBoss_Data_Grid_Project.html

--> incorrect or not ideal formatting


* http://documentation-stage.bne.redhat.com/docs/en-US/JBoss_Data_Grid/6/html/Getting_Started_Guide/Create_a_New_Cache_Manager.html

Cache defaultCache = manager.getCache();  ...it should be actually:
RemoteCache defaultCache = manager.getCache();


* http://documentation-stage.bne.redhat.com/docs/en-US/JBoss_Data_Grid/6/html/Getting_Started_Guide/Adding_and_Replacing_a_Key_Value.html
* http://documentation-stage.bne.redhat.com/docs/en-US/JBoss_Data_Grid/6/html/Getting_Started_Guide/Adjust_Data_Life.html

We cannot mention the file DefaultCacheQuickstart.java here. (The following procedure is an example that defines what each line entered into the DefaultCacheQuickstart.java file does:)
Users (even me) get easily confused because they do not know where to find the file. 


* http://documentation-stage.bne.redhat.com/docs/en-US/JBoss_Data_Grid/6/html/Getting_Started_Guide/sect-Use_a_Named_Cache.html

The following sentence should be either removed or changed: "If the custom cache is registered programatically, 
the configuration file must be loaded before it can be used. If the custom cache is registered declaratively, 
no configuration file loading is required. "

It's confusing. I would say it's vice versa - when the cache is registered declaratively the configuration file must be loaded
before it can be used. This sentence can be easily removed as it does not add any value.


* http://documentation-stage.bne.redhat.com/docs/en-US/JBoss_Data_Grid/6/html/Getting_Started_Guide/Register_the_Named_Cache_Using_XML.html
(related to Tomas' comment no. 3)

  The example of how to load the configuration file is 2 topics further: http://documentation-stage.bne.redhat.com/docs/en-US/JBoss_Data_Grid/6/html/Getting_Started_Guide/Load_the_Configuration_File.html
  I think the best would be to merge both topics into one (into the first one) or move the second topic right after the first one.


* http://documentation-stage.bne.redhat.com/docs/en-US/JBoss_Data_Grid/6/html/Getting_Started_Guide/Register_the_Named_Cache_Programmatically.html

We should not mention   CustomCacheQuickstart.java here. 


* http://documentation-stage.bne.redhat.com/docs/en-US/JBoss_Data_Grid/6/html/Getting_Started_Guide/Load_the_Configuration_File.html

Again, we should not mention the file. And another thing...the following sentence does not fit here: 
"Register the named cache programmatically." -> It's a configuration example where the cache is configured and registered declaratively.
Comment 1 Misha H. Ali 2012-06-07 21:46:21 EDT
1. Topic removed, according to QE recommendation.

* URL to be updated after the new contents appear on the stage.

2. The incorrect formatting issues are dealt with in another bug, so ignoring them in this one.

3. Corrected last line of configuration.

* http://documentation-stage.bne.redhat.com/docs/en-US/JBoss_Data_Grid/6/html/Getting_Started_Guide/Create_a_New_Cache_Manager.html

4. Removing references to DefaultQuickStart.java, need to consult with Tristan. This appears in several of the quickstart files and without stating where the configuration goes, it makes no sense.

5. Switched the two around, the final sentence should be correct now.

* http://documentation-stage.bne.redhat.com/docs/en-US/JBoss_Data_Grid/6/html/Getting_Started_Guide/sect-Use_a_Named_Cache.html

6. Merging or changing order of the topics mentioned by Tomas. This is addressed in a different bug with all of Tomas' comments, so ignoring in this bug.

7. Mention of CustomCacheQuickstart.java. Again, need to check with Tristan for a possible location.

8. Altered the header to declaratively, left off file name to be settled after consulting with Tristan.

* http://documentation-stage.bne.redhat.com/docs/en-US/JBoss_Data_Grid/6/html/Getting_Started_Guide/Load_the_Configuration_File.html
Comment 2 Misha H. Ali 2012-06-08 04:24:51 EDT
(In reply to comment #1)
> 1. Topic removed, according to QE recommendation.
> 
> * URL to be updated after the new contents appear on the stage.
> 

* http://documentation-stage.bne.redhat.com/docs/en-US/JBoss_Data_Grid/6/html/Getting_Started_Guide/chap-Run_JBoss_Data_Grid_as_an_Embedded_Cache.html

Topic is now removed.

> 4. Removing references to DefaultQuickStart.java, need to consult with
> Tristan. This appears in several of the quickstart files and without stating
> where the configuration goes, it makes no sense.
> 
> 7. Mention of CustomCacheQuickstart.java. Again, need to check with Tristan
> for a possible location.
> 
> 8. Altered the header to declaratively, left off file name to be settled
> after consulting with Tristan.
> 
Addressed in another bug, made the location of the quickstarts very obvious so locating them should not be a problem anymore.
Comment 3 Martin Gencur 2012-06-08 06:23:02 EDT
1) Can we please make the formatting nicer? (the matching XML tags should be at the same level horizontally.

Otherwise all my points were addressed. The docu is now much more understandable.
Comment 4 Martin Gencur 2012-06-08 06:23:33 EDT
Forgot to add the link with not-very-good formatting: http://documentation-stage.bne.redhat.com/docs/en-US/JBoss_Data_Grid/6/html/Getting_Started_Guide/Add_a_Profile_to_Your_Project.html
Comment 5 Misha H. Ali 2012-06-11 02:41:28 EDT
Same issue as another bug, but formatting is now correct. Please mark this bug VERIFIED if satisfied that all issues are resolved.
Comment 6 Martin Gencur 2012-06-11 04:09:08 EDT
That's how I'd imagined that:)

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