Documentation does not describe how to get started

[msakrejda]

The sarama reference documentation is solid, but getting started with the library based on just the built-in godoc docs is pretty rough: the API has a fairly large surface area, and given that godoc buries the examples after the initial index, they're easy to miss. We have several teams using sarama internally and none of them knew the examples existed. Even if one does find the examples, they're presented without much context or discussion: e.g., when should I use the sync versus the async producer, or the select versus goroutine pattern for async producing. For example, I think pq provides a clearer getting started doc (disclaimer: I am a pq maintainer).

It seems a first step here would be to link to examples, but the godoc format doesn't really support this. Maybe just add something like "For usage, see examples below" to the package-level docs? Thoughts?

[eapache]

the API has a fairly large surface area

Yes, we mean to move a lot of the low-level message construction into a separate package at some point, but it would mean a new major version and just hasn't seemed worth the effort so far.

given that godoc buries the examples after the initial index, they're easy to miss

I'll try and make those more obvious from the introductory paragraphs.

when should I use the sync versus the async producer, or the select versus goroutine pattern for async producing

This is kind of tricky, it depends a lot on the structure and needs of your specific application. I'll see what I can do, but providing sufficiently general advice here will be tricky.

One thing to note (specifically with respect to the pq comparison) is that generally people reading the pq docs are already familiar with what a database is and roughly how it works; I assumed a similar familiarity with Kafka when writing the Sarama docs. Sync-vs-async producing is a question more about kafka than about any specific producer implementation, so I'm not sure it makes sense to talk about it in-depth in our documentation.