[jbosscache-dev] Documentation feedback

[Kabir Khan]

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.
> 
> 
> 
> 
> 
> 
> 
> 
> 
> 
> 
> 
> 
> 
> 
> 
> 
> _______________________________________________
> jbosscache-dev mailing list
> jbosscache-dev at lists.jboss.org
> https://lists.jboss.org/mailman/listinfo/jbosscache-dev
>