I agree with your points about going into high levels of detail too quickly, and lacking introductory materials (including examples). Having all of these would be wonderful. This is the right discussion - let's figure out which docs we need, and what we need to carve out of existing docs.
On Tue, Dec 29, 2015 at 6:10 AM, Erb, Stephan <[email protected]> wrote: > 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
