trillian
trillian copied to clipboard
Rewrite README to be more user-focused
A sizeable portion of the README is currently dedicated to information only useful to developers working on the code. Instead, we should rewrite it to only contain information that users need. We can link to a separate document that covers what contributors need to know.
Information that the README should contain:
- [ ] Brief intro to Merkle trees and proofs
- [ ] How Trillian fits into a solution (e.g. part of the backend, but exposed via a personality, proofs passed to clients)
- [ ] Getting started
- [ ] Deploying Trillian
- Provide guidance around scaling and cost on Google Cloud.
- [ ] Examples of common API operations (e.g. queue a leaf and then poll for inclusion proof)
- Link to API documentation
- [ ] Designing a personality (why we have them, what they typically do, etc.)
- Link to https://github.com/google/trillian-examples
- [ ] Deploying a personality
- Link to CT deployment guide as an example
- [ ] Deploying Trillian
- [ ] Architectural diagrams
- Should reflect the Kubernetes components we've defined (e.g. logserver, logsigner, etcd, mysql)
- [x] Use cases
- [x] How to get further support (e.g. Slack, mailing list)
Information that should be moved out of the README:
- [ ] How to working on and test the code
- [ ] Detailed design information
- [ ] Map-related information (until it's no longer experimental)
I'm not sure that the main README should have that level of detail at all, esp. the architectural diagrams. Esp. Kubernetes!
I think it should be just an index of various things. An example of a good README from my PoV: https://github.com/cockroachdb/cockroach.
#1660 is related, we should make sure that the admin actions (e.g. creating trees) are part of the user docs.