[jbosscache-dev] Documentation feedback

[Vladimir Blagojevic]

Ok, enough about facking!!!

> -----Original Message-----
> From: Brian Stansberry 
> Sent: Monday, January 29, 2007 4:18 PM
> To: Kabir Khan; Vladimir Blagojevic; jbosscache-dev at lists.jboss.org
> Subject: RE: [jbosscache-dev] Documentation feedback
> 
> http://alt-usage-english.org/intro_d.shtml says it's 
> indeterminate due to differing pronunciation (some people say 
> "fack").  I think "an FAQ" sounds better. :-)
> 
> jbosscache-dev-bounces at lists.jboss.org wrote:
> > I actually think it is an FAQ, since it is pronounced "an 
> > Eef-Ay-Queue" :-)
> > 
> >> -----Original Message-----
> >> From: jbosscache-dev-bounces at lists.jboss.org
> >> [mailto:jbosscache-dev-bounces at lists.jboss.org] On Behalf 
> Of Vladimir 
> >> Blagojevic Sent: 29 January 2007 20:21
> >> To: jbosscache-dev at lists.jboss.org
> >> Subject: [jbosscache-dev] Documentation feedback
> >> 
> >> Here is my feedback. Cheers.
> >> 
> >> 
> >> Preface:
> >> 
> >> Rather than "Along with it's accompanying" it should be 
> "Along with 
> >> its accompanying". "an FAQ". Even I know that this is a wrong 
> >> preposition! "When used." Use capital. "A tree-structured, 
> >> clustered". Missing comma.
> >> 
> >> 
> >> Chapter 1:
> >> 1.1
> >> 
> >> "JBoss Cache is a tree-structured, clustered, transactional cache 
> >> from JBoss Cache." This sentence is confusing.
> >> 
> >> 1.1.1
> >> 
> >> "maintaining object references even affter replication or 
> >> persistence". Too many rrrss.
> >> "More on concurrency, locking and isolation levels will be 
> discussed 
> >> later". I would rather say "Concurrency, locking and 
> isolation levels 
> >> will be discussed later".
> >> 
> >> 1.2
> >> 
> >> "A The cache is organised as a tree, with a single root."
> >> Obvious preposition problem.
> >> 
> >> In this section writer goes on to describe what "we" do in 
> such and 
> >> such case. Maybe this can be rewritten not to say what we do but 
> >> rather what Jboss cache does. Just a matter of style. For example:
> >> "When a change is made to an object in the cache and that 
> change is 
> >> done in the context of a transaction, then we defer the 
> replication 
> >> of changes until the transaction commits successfully"
> >> becomes "When a change is made to an object in the cache and that 
> >> change is done in the context of a transaction, replication of 
> >> changes is deferred until the transaction commits successfully."
> >> 
> >> 2.2
> >> 
> >> "and an instance is is created"
> >> 
> >> 3.1
> >> 
> >> I would put introduction parameter *before* API image.
> >> 
> >> 3.4
> >> 
> >> I would put introduction parameter *before* API image. Should we 
> >> explain a bit more what pre boolean parameter is about as well as 
> >> isLocal parameter.
> >> 
> >> 3.5
> >> 
> >> Instead of term "CacheLoader(s)" use "cache loader(s)" when not 
> >> referring to a specific cache loader?
> >> 
> >> Mention not to use FileCacheLoader in production :)
> >> 
> >> 4.2
> >> 
> >> When we already mention that jboss cache is deployed as 
> >> jboss-cache.jar rather than the service archive the question 
> >> immediately pops up - why?
> >> 
> >> 
> >> 5.0
> >> 
> >> Link to compatibility page?
> >> 
> >> 
> >> 6.1
> >> 
> >> "How your data is organised" ?? Ugh. Maybe something else...
> >> 
> >> 6.3
> >> 
> >> How Calls Are Invoked On The Data Structure -> "Node invocations"
> >> 
> >> 6.3.3
> >> 
> >> "This context is one that holds intermediate state for the 
> >> duration..." -> "IvocationContext holds intermediate state for the 
> >> duration..."
> >> 
> >> I would rewrite this section like this:
> >> 
> >> InvocationContext holds intermediate state for the duration of a 
> >> single cache method invocation, and is set up and destroyed by the 
> >> InvocationContextInterceptor which sits at the start of the chain.
> >> 
> >> InvocationContext, as its name implies, holds contextual 
> information 
> >> associated with a single cache method invocation. Contextual 
> >> information includes associated javax.transaction.Transaction or 
> >> org.jboss.cache.transaction.GlobalTransaction, method 
> invocation node 
> >> origin (InvocationContext.isOriginLocal())
> >> as well as Option overrides (link ref).
> >> 
> >> InvocationContext can be obtained .blah blah blah...
> >> 
> >> 
> >> 7.1.2.1
> >> 
> >> "single modification os broadcast rather" -> "single 
> modification is 
> >> broadcast rather"
> >> 
> >> 
> >> 
> >> 8.1
> >> 
> >> loadEntireState and storeEntireState are outdated. They 
> refer to the 
> >> old implementation.
> >> 
> >> I would replace these with some description similar to current 
> >> javadocs.
> >> 
> >> http://labs.jboss.com/file-access/default/members/jbosscache/f
> >> reezone/do cs/2.0.0/api/org/jboss/cache/loader/CacheLoader.html
> >> 
> >> 
> >> 8.2
> >> 
> >> Shared is not explained in the same bullet point list as other 
> >> elements of configuration.
> >> 
> >> 
> >> 8.5 Strategies
> >> 
> >> Strategies of what? This section needs an introduction!
> >> 
> >> I would also add a use case for using several cacheloaders in a 
> >> chain. To be honest I never really understood the advantage of it.
> >> Increased fault tolerance? 
> >> 
> >> 
> >> 8.5.4 "Replicated Caches With Each Cache Having It's Own Store" -> 
> >> "Replicated Caches With Each Cache Having Its Own Store"
> >> 
> >> "When used with a transactionm anager". Typo.
> >> 
> >> What is the advantage of each cacheloader having its own 
> store? This 
> >> should be explained.
> >> 
> >> 8.5 Should explain tradeoffs of various strategies!
> >> 
> >> This is a very interesting JBC feature and a topic in 
> general to be 
> >> left in such non elaborated state.
> >> 
> >> 
> >> 
> >> 9.1.2
> >> 
> >> "eventQueueSize - this optional parameter defines how 
> large a queue 
> >> of items to evict to create". Huh???
> >> 
> >> policyClass explanation has several typos.
> >> 
> >> 
> >> 
> >> 9.2.1 timeToLiveSeconds . I do not understand this 
> parameter. Does it 
> >> mean that the node is swept away only if it has not be accessed in 
> >> certain period of time? Idle is not defined.
> >> 
> >> 
> >> 10.1.2.1
> >> 
> >> Isolation level explanation is a bit fuzzy. I like how isolation 
> >> levels are explained in clustering course material but I 
> am not sure 
> >> if we should include it here.
> >> 
> >> 
> >> 10.1.3.2
> >> 
> >> "it makes sense to aling the versions". Align spelling problem.
> >> 
> >> "in-memory reporesentation". Spelling.
> >> 
> >> 
> >> 11.2
> >> 
> >> Mention that ReplQueueInterval and ReplQueueMaxElements values are 
> >> considered only if UseReplQueue is true.
> >> 
> >> Mention that SyncReplTimeout should be bigger than 
> >> LockAcquisitionTimeout.