Documentation ... do it ... do it

[mhotan]

Background

Documentation is dramatically important regarding the prolonging the lifetime of any projects. Understanding what a project does, where its limited, and how to use it is imperative for contributers and users.

Requirements - Not Limited to but must include the following

• At the minimum follow Socrata README Standards
• Why use Eurybates instead of ActiveMQ directly?
• A Wiki describing issues like Architecture, Design Decisions, Why we wrote this...
• A Roadmap of where the project is going.

[vilterp]

My main question about this project: what does it provide that's better than directly using an ActiveMQ or Kafka library to push or listen to events? I think the README's main goal should be to answer that question.

For instance, the readme mentions that Eurybates imposes "some interesting requirements and design decisions", but only lists one: that it "automatically commits offsets every 10 seconds". What is the benefit of this decision? What are the other design decisions and requirements, and what are their benefits? It would be great if the readme listed these design decisions, and the pros and cons for each one.