[ZOOKEEPER-2090] Fix Zookeeper docs "To be done" notices

• Type: Bug
• Status: Open
• Priority: Trivial
• Resolution: Unresolved
• Component/s: documentation
• Labels: documentation

Environment

Official website

• Assignee: Unassigned
• Reporter: Hector
• Created: 25/Nov/14 14:54
• Updated: 13/Sep/16 18:32

Description

The docs on the website are full of TBDs since a long time ago. While there is not a full lack of docs, and you can get going with what there is, the main general-purpose entry points are not too polished and they give the impression ZK is not very well maintained to newcomers and anyone who just wants to see how ZK is progressing and refresh concepts.

The ZK overview doc (http://zookeeper.apache.org/doc/trunk/zookeeperOver.html) is supposed to be a first entry point for new Zookeeper users and it is full of [tbd]s:

When the session ends the znode is deleted. Ephemeral nodes are useful when you want to implement [tbd].

And if the connection between the client and one of the Zoo Keeper servers is broken, the client will receive a local notification. These can be used to [tbd].

Timeliness - The clients view of the system is guaranteed to be up-to-date within a certain time bound.

For more information on these, and how they can be used, see [tbd]

For a more in-depth discussion on these, and how they can be used to implement higher level operations, please refer to [tbd]

Some distributed applications have used it to: [tbd: add uses from white paper and video presentation.] For more information, see [tbd]

These znodes exists as long as the session that created the znode is active. When the session ends the znode is deleted. Ephemeral nodes are useful when you want to implement [tbd].

The second entry point, "Getting Started" (http://zookeeper.apache.org/doc/trunk/zookeeperStarted.html)

[tbd: what is the other config param?]

Programmers guide (http://zookeeper.apache.org/doc/trunk/zookeeperProgrammers.html)

"If the version it supplies doesn't match the actual version of the data, the update will fail. (This behavior can be overridden. For more information see... )[tbd...]"

Connecting to ZooKeeper

Read Operations

Write Operations

Handling Watches

Miscelleaneous ZooKeeper Operations

Program Structure, with Simple Example

[tbd]

ZooKeeper Whitepaper [tbd: find url]

The definitive discussion of ZooKeeper design and performance, by Yahoo! Research
API Reference [tbd: find url]

The complete reference to the ZooKeeper API

Administration guide (http://zookeeper.apache.org/doc/trunk/zookeeperAdmin.html)

Provisioning

Things to Consider: ZooKeeper Strengths and Limitations

Administering

TBD - tuning options for netty - currently there are none that are netty specific but we should add some. Esp around max bound on the number of reader worker threads netty creates.

TBD - how to manage encryption

TBD - how to manage certificates

Since it is not a big deal to fix these, I think it is worth it to spend some hours doing it.

Issue Links

• incorporates: ZOOKEEPER-815 fill in "TBD"s in overview doc
• incorporates: ZOOKEEPER-671 Lot of [tbd]-s ( missing links ? ) in the overview page
• incorporates: ZOOKEEPER-2431 C client documentation improvement