Status

Current state: "Accepted"

Discussion thread: http://mail-archives.apache.org/mod_mbox/bookkeeper-dev/201708.mbox/%3CCAO2yDyaxbA4BCGML2kHP4F1WjhQOKaTP7bVzc4dZemA0Y9%3DUdw%40mail.gmail.com%3E

JIRA: Issue #439

Released: 4.6.0

Motivation

In general, bookkeeper doesn't have very good documentation. In 4.5.0, we tried to improve the documentation as rewriting the website using markdown syntax and building with jekyll. The documentation looks much better than before. But the documentation itself is still lagging behind.  There are a few major areas that requires contributions and improvements, such as `Usage` (Tutorials, Examples and such), `Deployment`, `Operations` (Administration), `Development` (Internals, code structures).

Proposed Changes

Currently the new bookkeeper website has good layout about sections, `Getting Started`, `Deployment`, `Administration`, `API`, `Security` and `Development`. This proposal will be based on current layout, adding two new sections and improving individual existing sections.

Existing Sections

Following are list of changes proposed for each section.

Deployment

• Add a page about docker deployment.
• Add a page about deploying on k8s (including Google Cloud Platform, AWS)
• .. (add other deployment methods)

Administration

reorganize the pages under `Administration` in this order:

• Pre Deployment - e.g. Hardware considerations, Configuration settings
• Post Deployment - e.g. Monitoring, Tools, Software Upgrade, Bookie decommissions, Deploy AutoRecovery.

API

• Add a page about best practices
• Add pages about examples or tutorials
  • How to use API (ledger, advanced ledger or distributedlog apis) to develop different type of applications

Development

There was a proposal about documenting the internal details a while ago. We were proposing using wiki pages for achieving that. It hasn't completed due to lack of efforts. I am copying that structure here as the base layout for `Development`.

• Architecture
  • Basic Concepts
  • Request Flow
  • Bookie
    
    • Journal
    • Ledger Storage
    • Index
    • Garbage Collection
    • Compaction
  • Client
  • Metadata Management
  • Replication & Consistency
    • Fencing
    • LAC Protocol
  • Tail latency
    • Ack quorum and Ensemble change
    • Speculative reads
    • Long poll reads
  • Auto Recovery
• Code Structure

Reference

• 
  Fill up the details on `metrics` page

New Sections

Propose to add new sections:

• Performance: We can include the basic benchmark, how to run it, what is the results and include other reliability test results such as jepsen results.

Actions

This can be done by the collaboration in the community. We can create a master ticket and divide the work into individual sections and then divide into individual pages. Anyone who is willing to contribute to this can pick up an item and help fill up with content.

The community can review and help organizing the content.