[jira] [Updated] (OAK-5998) Clarify and complete missing stuff in current Oak documentation

["Davide Giannella (JIRA)" <ji...@apache.org>]

     [ https://issues.apache.org/jira/browse/OAK-5998?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel ]

Davide Giannella updated OAK-5998:
----------------------------------
    Fix Version/s:     (was: 1.7.3)
                   1.7.4

> Clarify and complete missing stuff in current Oak documentation
> ---------------------------------------------------------------
>
>                 Key: OAK-5998
>                 URL: https://issues.apache.org/jira/browse/OAK-5998
>             Project: Jackrabbit Oak
>          Issue Type: Documentation
>          Components: doc
>            Reporter: Chetan Mehrotra
>             Fix For: 1.8, 1.7.4
>
>
> Current Oak documentation [1] is missing details around certain aspects of Oak which makes it difficult for a new person to get up and running and more important operate Oak in productions easily. Purpose of this task is list out topic which must be documented to enable easier usage of Oak
> * Getting Started - Getting Oak with all features properly is tricky and not easily possible with our [current getting started|https://jackrabbit.apache.org/oak/docs/construct.html] specially for prod setup. 
> ** Possibly refer or move doc of current examples  here
> ** For a new user not aware of JCR but aware of document storage a brief overview on the JCR and how its the api for Oak which is to be used
> * Maintenance and Operations - 
> ** Oak being MVCC storage requires certain maintenance task like RevisionGC and BlobGC to be run periodically.  
> ** Then related MBean should be documented. Note some part is covered in [Segment docs|https://jackrabbit.apache.org/oak/docs/nodestore/segment/overview.html#garbage-collection] but we need to complete it for Document and also provide an overview
> ** System requirements in terms of RAM due to memory mapped usage, cloned index files and persistent cache
> * How clustering works in Oak - [Clustering doc|https://jackrabbit.apache.org/oak/docs/clustering.html] should provide details on 
> ** how it works
> ** importance of background read and background write
> ** Effect of eventual consistency in cluster setup 
> ** Sticky session requirement (as per usecase)
> * Observation
> ** How it works
> ** How external and local events are generated
> ** Queue behaviour and overflow
> * Clarify requirement from host application wrt 
> ** scheduling singleton jobs used in Oak and how they should be executed
> ** Scheduling maintenance operations via MBeans
> * Document various OSGi config - May be generate a doc for all OSGi config in Oak via some tooling
> Note list above is tentative and would be edited to determine important topics in coming days and then specific sub task can be created to complete it. Once any list item is completed add (/) against the list entry
> [1] https://jackrabbit.apache.org/oak/docs/



--
This message was sent by Atlassian JIRA
(v6.4.14#64029)