I actually think it is an FAQ, since it is pronounced "an Eef-Ay-Queue" :-) > -----Original Message----- > From: jbosscache-dev-bounces(a)lists.jboss.org > [mailto:jbosscache-dev-bounces@lists.jboss.org] On Behalf Of > Vladimir Blagojevic Sent: 29 January 2007 20:21 > To: jbosscache-dev(a)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.