Hi users, Hi developers, from personal experience, I can tell that the Aurora documentation is not the easiest one to approach. Most of the necessary information is somewhere, but often it is not obvious where to look for it.
Some thoughts: * We are missing a decent high-level introduction for beginners similar to one of the Singularity framework (https://github.com/HubSpot/Singularity/blob/master/Docs/details.md) * The userguide explains some high-level concepts but is also explaining the entire task lifecycle, thus going into too many details too quickly (https://aurora.apache.org/documentation/latest/user-guide/) * The recently added install instructions briefly explain many Aurora components. This information is probably better suited for the high-level documentation, as a proper understanding of the components is also needed elsewhere (https://aurora.apache.org/documentation/latest/installing/) * The configuration tutorial is rather hard on beginners as well (https://aurora.apache.org/documentation/latest/configuration-tutorial/). It would probably help to start with a simpler example and move the Pystachio details to another file. * A decent recipe or example collection similar to the one of Marathon (https://mesosphere.github.io/marathon/docs/recipes.html) would probably be very helpful. At the moment, most of these are only documented rather implicitly within various examples spread over the entire documentation. What are your thoughts on this? What should be added? What should be streamlined? Personally, I do believe that working on the documentation is high leverage and will easily pay off in the future. Thanks for your input, Stephan
