This is an automatically generated e-mail. To reply, visit:

Can we link this page from `home.md`?

Overall: looks great! Only major feedback is to move the implementation details 
down to the bottom (or remove them), and refactor things slightly so that any 
user-visible behavior (e.g., failover and capacity check heuristic) are 
discussed outside the "implementation details" section.

docs/quota.md (line 7)

    This seems a confusing way to start the document. How can a single 
framework "hog all of the resources?" While I can see how this is possible, I 
think it will be hard for many readers to grasp.
    I wonder if we should begin by quickly reviewing the quota-less DRF 
behavior, and showing how one framework can hog all the resoures. Then say how 
quota provides a means to avoid this.

docs/quota.md (line 21)

    Is the analogy between quota and dynamic reservation accurate/helpful? A 
dynamic reservation reserves _particular_ resources on a _specific_ agent, and 
the reservation fails if the resources are unavailable; quota just ensures that 
_sufficient_ resources in one or more agents are dedicated for the role. 
Calling quota a "cluster-wide dynamic reservation" doesn't capture this, IMO.

docs/quota.md (line 26)

    "that manages a Mesos cluster."

docs/quota.md (line 28)

    'In computer science, a "quota" usually..."

docs/quota.md (line 44)

    Period after "100 CPUs", not comma.

docs/quota.md (line 45)

    ", while fB is greedy..."

docs/quota.md (line 46)

    "fair share"
    "hogging the remaining 90 CPUs"

docs/quota.md (line 47)

    "the additional"

docs/quota.md (line 52)

    I think we want em-dash ("---") here, without spaces on either side. i.e., 
"resources---100 CPUs."

docs/quota.md (line 53)

    I'd put a comma after "joins the cluster".
    I'd say "it will not receive its fair share of the cluster resources (50 
CPUs) until ..."

docs/quota.md (line 56)

    Comma after "Scenario 2".

docs/quota.md (line 57)

    In Scenario 2, it is fB that uses all the resources, not fA.
    Remove "the" from "after the fA"

docs/quota.md (line 61)

    These kinds of implementation details belong at the bottom of the document, 
I think -- it is more important to tell the user/operator how to define quota 
before we worry about allocator details.
    We could also remove a lot of this information -- the specific steps we 
take to implement a set/remove quota request are not an important thing to 
document (and might change over time).

docs/quota.md (line 76)

    Why capitalize Quota here?
    Typically we want "e.g.," not "e.g."

docs/quota.md (line 82)

    You haven't told the reader what "the master endpoint" is.

docs/quota.md (line 106)

    Not sure this belongs in the implementation details section, because it 
influences user-facing behavior.

docs/quota.md (line 133)

    I found this sentence confusing.

docs/quota.md (line 180)

    "enables operators to configure quotas."

docs/quota.md (line 190)

    "set a new one."

docs/quota.md (line 192)

    "See the [...](auth...) for details."

docs/quota.md (line 198)

    "an HTTP", I'd think.

docs/quota.md (line 206)

    "12 CPUs", for consistency with the preceding text in the doc, I'd think.

docs/quota.md (line 226)

    Fix this link -- probably just link to roles.md. Although we don't really 
call the feature "implicit roles" in the user-facing docs (we just talk about 
whether a "role whitelist" has been configured), so maybe we can just remove 

docs/quota.md (line 240)

    "will receive"
    "HTTP response codes"

docs/quota.md (line 253)

    "an HTTP"

docs/quota.md (line 254)

    I'd just say "endpoint", we said "HTTP" in this sentence already.

docs/quota.md (line 259)

    "will receive"
    "HTTP response codes"

docs/quota.md (line 270)

    "query the configured quotas"

docs/quota.md (line 299)

    "will receive"
    "HTTP response codes"

docs/quota.md (line 306)

    "does not allow specifying" ("does not allow to specify" is ungrammatical). 
Similarly below.

- Neil Conway

On Jan. 7, 2016, 11:17 p.m., Joerg Schad wrote:
> -----------------------------------------------------------
> This is an automatically generated e-mail. To reply, visit:
> https://reviews.apache.org/r/42040/
> -----------------------------------------------------------
> (Updated Jan. 7, 2016, 11:17 p.m.)
> Review request for mesos, Alexander Rukletsov, Bernd Mathiske, Joris Van 
> Remoortere, and Neil Conway.
> Bugs: MESOS-3877
>     https://issues.apache.org/jira/browse/MESOS-3877
> Repository: mesos
> Description
> -------
> Added Quota Operator Documentation.
> Diffs
> -----
>   docs/quota.md PRE-CREATION 
> Diff: https://reviews.apache.org/r/42040/diff/
> Testing
> -------
> Rendered version: https://gist.github.com/joerg84/a2c32e25d91e33045b56
> Thanks,
> Joerg Schad

Reply via email to