[jira] [Created] (ZOOKEEPER-3282) a big refactor for the documetations

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

maoling created ZOOKEEPER-3282:
----------------------------------

             Summary: a big refactor for the documetations
                 Key: ZOOKEEPER-3282
                 URL: https://issues.apache.org/jira/browse/ZOOKEEPER-3282
             Project: ZooKeeper
          Issue Type: New Feature
          Components: documentation
            Reporter: maoling
            Assignee: maoling


Hi guys:

I'am working on doing a big refactor for the documetations.it aims to 

 - 1.make a better reading experiences and help users know more about zookeeper quickly,as good as other projects' doc(e.g redis,hbase).

 - 2.have less changes to diff with the original docs as far as possible.

 - 3.solve the problem when we have some new features or improvements,but cannot find a good place to doc it.

 

The new catalog may looks kile this:

* is new one added.

** is the one to keep unchanged as far as possible.

*** is the one modified.

--------------------------------------------------------------

|---Overview

    |---Welcome ** [1.1]

    |---Overview ** [1.2]

    |---Getting Started ** [1.3]

    |---Release Notes ** [1.4]

|---Developer

    |---API *** [2.1]

    |---Programmer's Guide ** [2.2]

    |---Recipes *** [2.3]

    |---Clients * [2.4]

    |---Use Cases * [2.5]

|---Admin & Ops

    |---Administrator's Guide ** [3.1]

    |---Quota Guide ** [3.2]

    |---JMX ** [3.3]

    |---Observers Guide ** [3.4]

    |---Dynamic Reconfiguration ** [3.5]

    |---Zookeeper CLI * [3.6]

    |---Shell * [3.7]

    |---Configuration flags * [3.8]

    |---Troubleshooting & Tuning  * [3.9]

|---Contributor Guidelines

    |---General Guidelines * [4.1]

    |---ZooKeeper Internals ** [4.2]

|---Miscellaneous

    |---Wiki ** [5.1]

    |---Mailing Lists ** [5.2]

--------------------------------------------------------------










The Roadmap is:

1.(I pick up it : D)

  1.1 write API[2.1], which includes the： 

    1.1.1  original API Docs which is a Auto-generated java doc,just give a link.

    1.1.2. Restful-api (the apis under the /zookeeper-contrib-rest/src/main/java/org/apache/zookeeper/server/jersey/resources)

  1.2 write Clients[2.4], which includes the: 

      1.2.1 C client 

      1.2.2 zk-python, kazoo

      1.2.3 Curator etc.......

      look at an example from: https://redis.io/clients




 #  write Recipes[2.3], which includes the:

  - integrate "Java Example" and "Barrier and Queue Tutorial"(Since some bugs in the examples and they are obsolete，we may delete something) into it.

  - suggest users to use the recipes implements of Curator and link to the Curator's recipes doc.

 
 #  write Zookeeper CLI[3.6], which includes the:

  - about how to use the zk command line interface [./zkCli.sh]

    e.g ls /; get ; rmr;create -e -p etc.......

  - look at an example from redis: https://redis.io/topics/rediscli

 
 #  write shell[3.7], which includes the:

   - list all usages of the shells under the zookeeper/bin. (e.g zkTxnLogToolkit.sh,zkCleanup.sh)

 
 #  write Configuration flags[3.8], which includes the:

   - list all usages of configurations properties(e.g zookeeper.snapCount): 

   - move the original Advanced Configuration part of zookeeperAdmin.md into it.

     look at an example from:https://coreos.com/etcd/docs/latest/op-guide/configuration.html

   
 #  write Troubleshooting & Tuning[3.9], which includes the:

   - move the original "Gotchas: Common Problems and Troubleshooting" part of Administrator's Guide.md into it.

   - move the original "FAQ" into into it.

   - add some new contents （e.g https://www.yumpu.com/en/document/read/29574266/building-an-impenetrable-zookeeper-pdf-github）.

   look at an example from:https://redis.io/topics/problems

                              https://coreos.com/etcd/docs/latest/tuning.html

 
 #  write General Guidelines[4.1], which includes the:

  - move the original "Logging" part of ZooKeeper Internals into it as the logger specification.

  - write specifications about code, git commit messages,github PR  etc ...

    look at an example from:

    http://hbase.apache.org/book.html#hbase.commit.msg.format

 
 #  write Use Cases[2.5], which includes the:

  - just move the context from: https://cwiki.apache.org/confluence/display/ZOOKEEPER/PoweredBy into it.

  - add some new contents.(e.g Apache Projects:Spark;Companies:twitter,fb)

 

--------------------------------------------------------------

BTW:

- Any insights or suggestions are very welcomed.After the dicussions,I will create a series of tickets(An umbrella)

- Since these works can be done parallelly, if you are interested in them, please don't hesitate,just assign to yourself, pick it up. (Notice: give me a ping to avoid the duplicated work).



--
This message was sent by Atlassian JIRA
(v7.6.3#76005)