trillian icon indicating copy to clipboard operation
trillian copied to clipboard

Rewrite README to be more user-focused

Open RJPercival opened this issue 7 years ago • 2 comments

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

RJPercival avatar Nov 23 '18 16:11 RJPercival

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.

pav-kv avatar Feb 09 '21 15:02 pav-kv

#1660 is related, we should make sure that the admin actions (e.g. creating trees) are part of the user docs.

AlCutter avatar May 26 '22 10:05 AlCutter