Uploaded image for project: 'ZooKeeper'
  1. ZooKeeper
  2. ZOOKEEPER-3282

a big refactor for the documetations

    XMLWordPrintableJSON

    Details

    • Type: Task
    • Status: In Progress
    • Priority: Major
    • Resolution: Unresolved
    • Affects Version/s: None
    • Fix Version/s: None
    • Component/s: documentation
    • Labels:
      None

      Description

      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

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

       

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

       

      1. write shell[3.7], which includes the:

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

       

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

        

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

       

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

       

      1. 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).

        Attachments

          Issue Links

            Activity

              People

              • Assignee:
                maoling Ling Mao
                Reporter:
                maoling Ling Mao
              • Votes:
                0 Vote for this issue
                Watchers:
                1 Start watching this issue

                Dates

                • Created:
                  Updated:

                  Time Tracking

                  Estimated:
                  Original Estimate - Not Specified
                  Not Specified
                  Remaining:
                  Remaining Estimate - 0h
                  0h
                  Logged:
                  Time Spent - 6h 50m
                  6h 50m