You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@zookeeper.apache.org by Justin Ling Mao <ma...@sina.com> on 2019/02/13 13:48:01 UTC
回复：A big refactor for the documetations
ping @anmolnar and others, any insights or suggestions ?
----- 原始邮件 -----发件人："Justin Ling Mao" <ma...@sina.com>
收件人："dev" <de...@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: https://redis.io/topics/rediscli
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 https://coreos.com/etcd/docs/latest/tuning.html
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).
Re: A big refactor for the documetations
Posted by Norbert Kalmar <nk...@cloudera.com.INVALID>.
Hi,
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.
Regards,
Norbert
On Wed, Feb 13, 2019 at 2:48 PM Justin Ling Mao <ma...@sina.com>
wrote:
> ping @anmolnar and others, any insights or suggestions ?
> ----- 原始邮件 -----发件人："Justin Ling Mao" <ma...@sina.com>
> 收件人："dev" <de...@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:
> https://redis.io/topics/rediscli
> 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
> https://coreos.com/etcd/docs/latest/tuning.html
> 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).