[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/freezone/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.