zookeeper-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Justin Ling Mao" <maoling199210...@sina.com>
Subject 回复:回复:Re: A big refactor for the documetations
Date Thu, 14 Feb 2019 06:33:24 GMT
Thanks for your ACK @Norbert!
--->"I think the formatting is broken, it was a bit hard to read through." 
      Wuuu,it's ok in my side.You can also read this Google Doc:
--->"I'm not sure we want to change the formatting of the docs though"
      the new catalog use the origin doc skeleton,and almost only add some new navigation
--->"It's been similar for a long time, and I guess people got used to it :)"
      the fact is that people complain about that docs for a long time.:D.
Our doc is inferior to other projects (e.g. redis,hbase,etcd....).it is the time to bring
forth the new through the old.
----- 原始邮件 -----
发件人:Norbert Kalmar <nkalmar@cloudera.com>
收件人:dev@zookeeper.apache.org, maoling199210191@sina.com
主题:Re: A big refactor for the documetations
日期:2019年02月13日 22点26分

I think the formatting is broken, it was a bit hard to read through.I think it's a good idea,
especially adding new stuff like 3rd party tools Curator and examples. I'm not sure we want
to change the formatting of the docs though. It's been similar for a long time, and I guess
people got used to it :) But I'm not against it either.
So definitely +1 on adding new stuff and example, and I'm neutral on the changing the doc
format part. It has its pros and cons. 
On Wed, Feb 13, 2019 at 2:48 PM Justin Ling Mao <maoling199210191@sina.com> wrote:
ping @anmolnar and others, any insights or suggestions ?

----- 原始邮件 -----发件人:"Justin Ling Mao" <maoling199210191@sina.com>

收件人:"dev" <dev@zookeeper.apache.org>

主题:A big refactor for the documetations

日期:2019年02月12日 11点50分

Hi gugs: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

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

3. 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:

4. write shell[3.7], which includes the:   - list all usages of the shells under the zookeeper/bin.
(e.g zkTxnLogToolkit.sh,zkCleanup.sh)

5. 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
  6. 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                               

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

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

  • Unnamed multipart/alternative (inline, None, 0 bytes)
View raw message