[jbosscache-dev] comments on 2.0 BETA1 documentation

[Manik Surtani]

Thanks - will look into it.  :-)

Keep the feedback coming in, ppl!
--
Manik Surtani

Lead, JBoss Cache
JBoss, a division of Red Hat

Email: manik at jboss.org
Telephone: +44 7786 702 706
MSN: manik at surtani.org
Yahoo/AIM/Skype: maniksurtani



On 29 Jan 2007, at 11:24, Galder Zamarreno wrote:

> Hi,
>
> Over the weekend, I read the documentation for 2.0 BETA1 taken from  
> http://tinyurl.com/36q634. Here are my comments:
>
> Preface
> - 2nd paragraph, "when" should start with capital letter.
> - "information around this" might sound better "information about  
> this"
> - "use the JBoss Cache as a clustering", I would remove "the"
> - 3rd paragraph, "it's" should "its"
>
> 1.1.
> - "JBoss Cache... from JBoss Cache", it sounds like a repetition.
> - "is" repeated
>
> 1.2
> - Lists lines don't have dots at the end of line, they do in  
> previous section; consistency preferred.
> - "A The Cache is organised as a tree..."; remove The
> - "propagate any changes to all other replicated trees". Maybe you  
> wanna make a brief intro to buddy replication?
> - Last paragraph, last sentence, "will be discussed" seems out of  
> place, "more on this later" sounds better to me.
>
> 1.3.
> - Only some of the dependencies noted. Either list all or say that  
> these are some of them.
>
> 2.2
> - 1st paragraph, 2nd line, "is" repeated.
>
> 2.4
> - A code example using Option might be useful?
>
> 3.5
> - Mention c3p0 in JDBCCacheLoader within the list of shipped  
> implementations
>
> 4.1.
> - Comma missing after "CacheFactory and,"
>
> 4.2.
> - "is run" should be "runs"
> - Second paragraph, it might be better to refer to server's lib  
> directory rather than /lib dir in case people confuse it with root / 
> lib
>
> 4.3.
> - It might be worth noting binding to JNDI allows the cache to be  
> accessed remotely via the invoker specified.
>
> 4.5.3
> - It might help adding imports to second code example
>
> 4.5.4
> - Second paragraph, addition spelled incorrectly
>
> 6.1
> - Last paragraph, should be "Any modifications"
>
> 6.4.3
> - It's SingletonStoreCacheLoader not, SingletonCacheLoader
>
> 6.5.3
> - Disabling jboss serialization is done with "- 
> Dserialization.jboss=false". All JBoss properties follow the  
> "jboss.x" notation, should we follow similar for this as well?
>
> 7.1.2
> - Same as in 1.2, this section will mention buddy replication so  
> you might wanna reword starting sentence?
> - Is it worth mentioning when is replication queue recommended  
> using? I.e. REPL_ASYNC without TXs?
> - 3rd paragraph, "applie at all nodes", sounds better "applied to  
> all nodes"
> - 3rd paragraph, "this is not be the case", is this correct? "this  
> might not be the case" sounds better to me.
>
> 7.1.2.2.3
> - "My default" should be "By default"
>
> 7.3.1
> - We need consistency on how configuration parameters are written,  
> whether monospaced or not and whether to start them with capital  
> letters or not. See last line in first basic type and 2nd paragraph  
> in 2nd basic type.
> - In state transfer types, CacheLoaderPreload is the old fashion  
> way to define preloading.
> * There's a few of these in the CacheLoader section too.
>
> 7.3.2.
> - "2." section, "Here" should be "Here," ?
> - "3." Section, 3rd line, "it's" should be "its"
>
> 8.1.
> - "For example, here a database CacheLoader" does not sound  
> alright, maybe punctuation change?
>
> 8.2.
> - 2nd paragraph, is the "Note that," located in the right place,  
> the paragraph is talking about CacheLoader class
>
> 8.2.
> - <shared> is not explained here, maybe it's worth noting that it's  
> explained later in the Strategies section?
>
> 8.3.
> - It might be worth mentioning the package where these  
> implementations are located. All of them are under o.j.c.loader  
> except Bdje and Jdbm.
> - I have just realised that it's only JDBCCacheLoader that is  
> currently using VAM instead of serialization. Bdje and Jdbm do  
> their own way, but FCL is still using normal serialization. I guess  
> we want FCL to use VAM as well, correct?
>
> 8.3.1.
> - "adding check.character.portability" is supposed to be added to  
> the properties element. This should be noted.
>
> 8.3.4
> - Paragraph before last, first line, should be "instances"
>
> 8.5.4
> - "When used with a transactionm anager" should be corrected
>
> 9.1.1
> - policyClass explanation should start with "this is required" and  
> "one os not defined" should be corrected.
>
> 10.1.
> - first line, should be "its" rather than "it's"
>
> 10.1.1.
> - Maybe we should mention how we acquired WL locks when inserting/ 
> removing children?
>
> 10.1.3.1
> - should be "its workspace" rather than "it's workspace"
>
> 10.1.3.2
> - "representation" rather than "reporesentation"
>
> 10.2.
> - Shall we mention that GenericTMLookup will fallback in DummyTM if  
> it found none?
>
> 11.2
> - Same as we recommended InitialStateRetrievalTimeout should be  
> longer than LockAcquisitionTimeout, we should say the same for  
> SyncReplTimeout.
> - UserInterceptorMBeans: mbeans in lower case, we should be  
> consistent and write it the same way in the document, as MBean(s)
>
> 12.2.
> - Change CacheListener events to be the same as the enums defined  
> in CacheListenerEvent.ListenerMethod, shouldn't it?
>
> Cheers,
>
> Galder Zamarreño
> Sr. Software Maintenance Engineer
> JBoss, a division of Red Hat
>
>
>
> _______________________________________________
> jbosscache-dev mailing list
> jbosscache-dev at lists.jboss.org
> https://lists.jboss.org/mailman/listinfo/jbosscache-dev