BP-12 - Improve documentation

[sijie]

Created a master issue for BP-12

How does it work?

If you are interested in contributing to this big project, feel free to pick up any items by doing as follows:

• if you are committers, you can create an issue and append the issue and you github id to an item: for example, '- [ ] item : #{issue-id} @{github-login}'
• if you are contributors, you can create an issue for the item you want to work on, and comment here, saying "i'd like to work on xxx, and here is the #{issue_id}". committers will update the description for you

What can you work on?

If you are new to this project, you can contribute to this by playing around the library and write tutorials or examples. If you are not familiar with one area but still like to contribute, try to pick up an item and fill up the content that you know, the committers will help improve it. It is also a good chance to learn more about bookkeeper when writing docs.

Sections:

Deployment

• [ ] Deployment
  • [ ] Add a page about docker deployment.
  • [x] Add a page about deploying on k8s (including Google Cloud Platform, AWS) #682 #461
  • [ place holder - add more deployment methods ]

Administration

• [ ] 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
  • [ place holder - add more administration related topics ]

API

• [ ] 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
  • [ ] How to use bookkeeper in embedded environment (network less or local mode)
  • [ place holder - add more examples, tutorials ]

Development

• [ ] Development: rewrite the development section following the structure below.
  • [ ] 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

• [ ] Reference
  • [ ] Fill up the details on metrics page

Performance

• [ ] 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.

[sudoHackIn]

Hi,@sijie, what actually documentation about docker deployment should be? this docker-image information (including docker-compose example) is good enough for me. Should we provide additional link to it from "Docker deployment" section?

[shoothzj]

closing for inactivity. feel free to reopen