google / google/trillian

Rewrite README to be more user-focused

Open
#1,357 2 comments 0 reactions 0 assignees View on GitHub
docs enhancement Low Priority
Dominant language
Go
Stars
3.7k
Forks
465
Avg merge
2d 16h
Merged PRs (30d)
5

Description

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](https://github.com/google/certificate-transparency-go/blob/9ec921f60b49b3708d52e1b37aa9b5596cb8f4b9/trillian/docs/ManualDeployment.md) as an example
- [ ] 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)

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.