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

["Charles Grossman (JIRA)" <ji...@apache.org>]

    [ https://issues.apache.org/jira/browse/OAK-5998?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=15952452#comment-15952452 ] 

Charles Grossman commented on OAK-5998:
---------------------------------------

I wish there were more "Up and running articles"

for example:
How to use Oak in a RatPack Project
How to use Oak in a  Grails Project
How to use Oak in a SpringBoot Project
How to use Oak in a Groovy Project

Just a simple app for each that boots and show the repo being loaded would be cool on the landing page.

Also the code base being in Maven makes it difficult since it seems a lot of these projects have moved to Gradle (i know it's not apache but still...it's being used a ton) -- it would be nice if there was a Gradle Build file you could use for the above items, or some kind of lazybones generator --> that work out of box as a starting point.

It would be nice if you guys used Git instead of Subversion, or at least had a Git Repo you could use in lieu of subversion.  

I've not tried to use Oak in a few months so forgive me if I am wrong and some of the above items have been addressed.  I will be looking at it again shortly, mainly trying to utilize it into a Grails or RatPack app.


> 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.7.0, 1.8
>
>
> 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.3.15#6346)