[jbosscache-dev] Documentation feedback

[Brian Stansberry]

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 at 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 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.