> On Jan. 7, 2016, 11:55 p.m., Neil Conway wrote:
> > docs/quota.md, line 226
> > <https://reviews.apache.org/r/42040/diff/1/?file=1186512#file1186512line226>
> >
> >     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 this.
> 
> Alexander Rukletsov wrote:
>     Though it indeed seems weird to mention random features in this user doc, 
> I would love to mention implicit roles somewhere here. The motivation is that 
> it's a new (read: relatively unknown) feature, which is highly related to 
> quota. I would like to make sure an operator reading this doc is aware of the 
> feature and can use it appropriately. The best solution would be to add a 
> `NOTE` or a sentence and remove it in ~6 month, when implicit roles become 
> standard. Unfortunately, we do not support remove `TODO`s in user docs : )

Maybe we can rephrase this to talk in terms of whether a "role whitelist" has 
been configured?


> On Jan. 7, 2016, 11:55 p.m., Neil Conway wrote:
> > docs/quota.md, line 61
> > <https://reviews.apache.org/r/42040/diff/1/?file=1186512#file1186512line61>
> >
> >     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).
> 
> Alexander Rukletsov wrote:
>     Our intention was *not* to provide implementation details, but to mention 
> some of those, which are important and affect cluster behaviour. There are 3 
> things: capacity heuristic, rescinding offers, allocator logic (quota first, 
> fair share second). I do think we should explain operators how these things 
> work so that they don't break their clusters.
>     
>     However, if the section feels like an "implementation details" section, 
> we didn't achieve our goal. The reason we decided to briefly mention other 
> stages is in order not to be misleading and leave an impression, that there 
> is nothing else.
>     
>     Do you think leaving only these 3 sections and adding a sentence that 
> those are most important stages in quota processing is a good compromise?

I think we could improve things in two ways:

1. Move the "How does it work?" section to the end of the document. Although 
this is useful material, it is fairly advanced; a lot of users will want to 
just know how to configure/examine quota.
2. Remove some of the implementation details. For example, the fact that we 
authenticate, parse, validate, and authorize a quota request is not important 
for the information we want to convey to operators about how quotas behave.


- Neil


-----------------------------------------------------------
This is an automatically generated e-mail. To reply, visit:
https://reviews.apache.org/r/42040/#review113358
-----------------------------------------------------------


On Jan. 8, 2016, 10:26 a.m., Joerg Schad wrote:
> 
> -----------------------------------------------------------
> This is an automatically generated e-mail. To reply, visit:
> https://reviews.apache.org/r/42040/
> -----------------------------------------------------------
> 
> (Updated Jan. 8, 2016, 10:26 a.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/home.md 6f0f4b9cb9d0da1f9960ebe7f36ce186c1317535 
>   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