gojek/ziggurat

README Improvements

mjayprateek opened this issue · 2 comments

mjayprateek commented

This ticket captures all the improvements one wants to see in Ziggurat README. Please comment below with your wishlist item for Ziggurat README. All of those will be taken up as a part of this ticket.

  • Structuring of README should be improved. At present, it makes a lot of assumptions about the potential reader - knowledge of clojure, concept of streaming, Kafka, etc. But, that's not always true. Every README should be written targeting a novice (to Ziggurat and associated technologies, obviously).
    It should start with a brief introduction to Ziggurat, a section on important concepts with a short list on further reads, and an example driven step-by-step guide for getting an app up and running with all major features provided by Ziggurat - streams, routes, metrics, producer, testing, etc. And obviously, an upgrade guide. This structure is just my thought of a good readme. One should look at good external examples for inspiration.

  • A section on concepts would really help a newbie developing a good understanding of the components such as consuming from Kafka Streams and retries using RabbitMQ. At present, README clearly lacks any information about how retries and queues work in Ziggurat.

  • [Configuration] README should specify the recommended value for all the configurations in Ziggurat, which aligns with the best practices for the system/tool/framework. Also, every such recommendation should be accompanied by an external link which endorses such a recommendation.
    For example, Ziggurat based apps should configure stream-threads-count ideally as Number of total partitions/Number of stream tasks. Things like would help a newbie to avoid the usual pitfalls due to wrong configurations.

macalimlim commented

A sample actor code repository(ies) to supplement the code samples in the readme. samples should at least show howto use ziggurat in a most basic use case.

WickedBrat commented

WIP list:

  • FAQs for debugging the changes made and its testing.
  • Steps to test local Ziggurat build with a custom actor.