More documentation needed

autarch opened this issue 6 years ago · 1 comments

I'm trying to read through the v1 example scheduler but it's very difficult to follow. It calls a lot of APIs that are barely documented. Even when a func is documented it's usually just a very minimal description of what it does.

What's missing is any context. I have no idea why any of these calls are important, nor do I have any clue of how this all fits together.

What I'd like to see is much more detailed documentation that explains both what a func does and why I would use it, along with references to how it fits in with other parts of the API.

Now I'm sure patches are welcome but I'm really not in a position to offer one. I don't see how anyone could do this without extremely intimate knowledge of the code base.

Answer 1 · 2019-02-13T17:56:58.000Z

Thanks for the feedback. mesos-go assumes that the reader already has some familiarity w/ Mesos and how to interact w/ Mesos using the v1 APIs. The examples aren't really crafted in the spirit of a guided tutorial, but instead as a way to bootstrap framework development. So your feedback makes sense: the examples aren't trying to solve the problem that you seem to be asking for help with.

FWIW the canonical Mesos v1 API references are here:

There's some documentation on the Mesos site to help those interested in building frameworks, e.g. http://mesos.apache.org/documentation/latest/app-framework-development-guide/.

There's at least one book dedicated to Mesos concepts and how to get started building frameworks: http://shop.oreilly.com/product/0636920039952.do

That said, let's keep this ticket open since I do agree that more documentation would be helpful to newcomers.