[jbosscache-dev] Documentation feedback

Mon Jan 29 17:29:07 EST 2007

LOL!
--
Manik Surtani

Lead, JBoss Cache
JBoss, a division of Red Hat

Email: manik at jboss.org
Telephone: +44 7786 702 706
MSN: manik at surtani.org
Yahoo/AIM/Skype: maniksurtani


On 29 Jan 2007, at 21:33, Vladimir Blagojevic wrote:

> Ok, enough about facking!!!
>
>> -----Original Message-----
>> From: Brian Stansberry
>> Sent: Monday, January 29, 2007 4:18 PM
>> To: Kabir Khan; Vladimir Blagojevic; jbosscache-dev at 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 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.
>
> _______________________________________________
> jbosscache-dev mailing list
> jbosscache-dev at lists.jboss.org
> https://lists.jboss.org/mailman/listinfo/jbosscache-dev