RE: [jbosscache-dev] Documentation feedback

-----Original Message----- From: Brian Stansberry Sent: Monday, January 29, 2007 4:18 PM To: Kabir Khan; Vladimir Blagojevic; jbosscache-dev(a)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(a)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(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.