Re: [jbosscache-dev] Documentation feedback

Ok, enough about facking!!! > -----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. _______________________________________________ jbosscache-dev mailing list jbosscache-dev(a)lists.jboss.org https://lists.jboss.org/mailman/listinfo/jbosscache-dev