> 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 > >
