What makes an excellent design doc

Replicache Detailed Design(https://doc.replicache.dev/design):

Replicache runs alongside your existing application infrastructure. You keep your existing server-side stack and client-side frameworks. Replicache doesn’t take ownership of data, and is not the source of truth. Its job is to provide bidirectional sync between your clients and your servers. This makes it easy to adopt: you can try it for just a small piece of functionality, or a small slice of users, while leaving the rest of your application the same.

Conflicts are a fact of life when syncing, but they don’t have to be painful. Replicache rewinds and replays your transactions during sync, sort of like git rebase.

I haven’t used Replicache, but this design document makes me think it has the qualities that excite me when I discover infrastructural software:

  • it solves a tricky problem (distributed application state)
  • by compressing the problem down to essential concepts
  • those concepts are solved in a way that I can imagine “how would I use this?”
  • and writing clearly about that solution
Adam Keys @therealadam