Doc tweaks for paper resubmission #374

dylanbannon · 2020-08-12T00:10:33Z

Updating Kiosk diagram, both XML file for draw.io and resulting PNG.
Adding section to developer docs about verifying benchmarking numbers.

docs/source/DEVELOPER.rst

docs/images/Kiosk_Architecture.xml

willgraf · 2020-08-12T23:33:35Z

I've built it via RTD. There are definitely rendering problems. It looks like you're trying to write Markdown, but this is RST.

docs/source/DEVELOPER.rst

MekWarrior · 2020-08-14T21:20:58Z

The docs will built it via RTD highlight a number of remaining rendering issues. The use of bold in certain contexts is odd and bullet style is inconsistent. Neither match the rest of the docs. I would also prefer the figure making portion be moved to the figure repo. Even with that, this section constitutes over half of the developer documentation. If it is going to remain this verbose and fastidious, perhaps it would be better to house it on a different page?

dylanbannon · 2020-08-14T21:45:07Z

@MekWarrior
I'll remove the bold and reorganize things to that it's hopefully more concise. After that, I'm absolutely open to moving the benchmarking documentation to its own file if it still makes sense.

Moving the figure creation to the publication-figures repo doesn't quite make sense to me, since the figure recreation section here seems to dovetail well with the instructions in the README of the other repo. Is there some other way to make this section fit in better with the rest of the doc?

MekWarrior · 2020-08-14T21:50:52Z

@dylanbannon my supposition would be that we have a number of different repos that we point to from this one. As the figure making is already self contained, it would seem consistent with our approach that one would come to this portion of the docs for information on benchmarking and to the figure repo for information on figure making (and there's no reason we can't cross-link the 2). Moreover, it would help unclutter the docs on our primary repo, making it easier for users to parse and use.

willgraf · 2020-08-14T21:55:44Z

It does seem natural to point them to the publication repo and say something like:

With the completed benchmarking runs you can use our graph generation repository to regenerate your own charts.

dylanbannon · 2020-08-14T22:14:05Z

Ok, I pushed a rearranged commit. So, you guys think everything in the two figure recreation subheadings should be moved to the publication-figures repo and replaced with a pointer?

dylanbannon · 2020-08-14T22:23:20Z

Also, I merged the version2 branch into master in the publication-figures repo, like you suggested @MekWarrior. I'm still having an issue with cloning the repo, though. Can anyone recreate vanvalenlab/publication-figures#2?

…ily moved over to publication-figures

docs/source/DEVELOPER.rst

Co-authored-by: willgraf <[email protected]>

docs/source/DEVELOPER.rst

willgraf

The storage bucket icon is much improved!

I don't like that arrows between Redis/Frontend and Redis/Autoscaler are off center. For some reason it really stands out to me.

Maybe we can move the purple GPU zone further into the corner to allow the straight line between redis and the frontend to be in the middle of the frontend icon?

I think the TF/ConsumerB arrow needs to be closer to the center of the TF icon as well, it looks weird to me that it's so close to the edge.

docs/source/DEVELOPER.rst

Co-authored-by: willgraf <[email protected]>

willgraf

I'm pretty satisfied with both the text and the image, but we should get input from both @MekWarrior and @vanvalen.

MekWarrior · 2020-08-21T04:39:03Z

I think the architecture diagram looks much better. I feel like there are still some issues with spacing and centering, but I could be ok with this if vanvalen approves. Text reads well.

willgraf · 2020-08-21T23:15:58Z

I was looking at the image a bit more, and the blank space inside the purple GPU zone is bothering me. I'll see if I can mock up some changes that might help.

I took a stab at fixing some things, and just opened a PR for the changes. It's not necessary to merge it in, but I thought it would help better show some of the things I wanted fixed.

willgraf

I made a last-minute change to the image (Consumer A was on both icons). It all looks good to me now.

@dylanbannon Thanks for your patience in dealing with so much of my nitpicky feedback!

MekWarrior

2 very minor changes and I'm good to go.

docs/source/DEVELOPER.rst

Co-authored-by: MekWarrior <[email protected]>

MekWarrior

Looks good! Thank you for the changes

willgraf

💯 🥇

* Fix documentation badge (#354) * Bump redis-consumer versions to 0.6.1. (#355) * If no default-region is selected, use us-west1 (#358) * Clarify Quota increase documentation (#359) * GPUS_ALL_REGIONS does not always exist in the quota, if not just set it to minimum. (#362) * Fix last references to old project name. (#364) * set prometheusOperator.cleanupCustomResource to true to delete CRDs when the chart is deleted. (#365) * Warn the user that multizone clusters will have additional egress fees. (#366) * Remove deprecated helmfiles. (#368) * General documentation fixes. (#360) * update documentation in version to 1.2.1 in preparation for pending release. (#371) * Doc tweaks for paper resubmission (#374) * Set the KUBERNETES_VERSION to 1.15. 1.14 is no longer supported. (#376) Co-authored-by: willgraf <[email protected]> Co-authored-by: dylanbannon <[email protected]> Co-authored-by: MekWarrior <[email protected]>

dylanbannon added 2 commits August 11, 2020 13:59

these are the files that correspond to figure S1

78cfa80

adding benchmarking documentation

a172fa4

dylanbannon requested review from willgraf and MekWarrior August 12, 2020 00:10

dylanbannon self-assigned this Aug 12, 2020

dylanbannon added the documentation A change in documentation is requested label Aug 12, 2020

dylanbannon changed the base branch from master to stable August 12, 2020 00:11

MekWarrior requested changes Aug 12, 2020

View reviewed changes

willgraf reviewed Aug 13, 2020

View reviewed changes

dylanbannon added 3 commits August 14, 2020 11:49

cleaning up benchmarking documentation

101bf1d

added in instructions on reproducing the figures from the paper

5b593f8

fixing RST errors

0fd6e1b

willgraf reviewed Aug 14, 2020

View reviewed changes

sequestering all benchmarking figure talk in its own subsections

2700a42

dylanbannon added 2 commits August 14, 2020 15:30

cleaned up so that the two benchmarking figure subsections can be eas…

99b41a0

…ily moved over to publication-figures

moving figure recreation details to publication-figures repo

bca6e73

dylanbannon requested review from MekWarrior and willgraf August 14, 2020 22:52

willgraf requested changes Aug 15, 2020

View reviewed changes

dylanbannon and others added 4 commits August 16, 2020 23:19

Update docs/source/DEVELOPER.rst

8a77bb0

Co-authored-by: willgraf <[email protected]>

Update docs/source/DEVELOPER.rst

070e0aa

Co-authored-by: willgraf <[email protected]>

Update docs/source/DEVELOPER.rst

a2da26c

Co-authored-by: willgraf <[email protected]>

Update docs/source/DEVELOPER.rst

0ea2ff7

Co-authored-by: willgraf <[email protected]>

dylanbannon requested a review from willgraf August 20, 2020 07:25

willgraf reviewed Aug 20, 2020

View reviewed changes

docs/source/DEVELOPER.rst Outdated Show resolved Hide resolved

willgraf reviewed Aug 20, 2020

View reviewed changes

dylanbannon added 2 commits August 20, 2020 11:40

updating link to publication-figures repo

879cbcc

cleaning up architecture diagram

78fb3d9

dylanbannon requested a review from willgraf August 20, 2020 18:55

willgraf reviewed Aug 20, 2020

View reviewed changes

docs/source/DEVELOPER.rst Outdated Show resolved Hide resolved

dylanbannon and others added 2 commits August 20, 2020 12:25

Update docs/source/DEVELOPER.rst

93fa582

Co-authored-by: willgraf <[email protected]>

scaling to the desired dpi

95affa4

dylanbannon requested a review from willgraf August 20, 2020 19:31

willgraf reviewed Aug 20, 2020

View reviewed changes

dylanbannon requested a review from vanvalen August 20, 2020 23:30

willgraf added 2 commits August 24, 2020 14:59

Upate spacing in architecture diagram (#375)

446d537

One of the consumers should be "Consumer B".

31aa66f

willgraf self-requested a review August 24, 2020 22:16

willgraf previously approved these changes Aug 24, 2020

View reviewed changes

MekWarrior requested changes Aug 24, 2020

View reviewed changes

docs/source/DEVELOPER.rst Outdated Show resolved Hide resolved

docs/source/DEVELOPER.rst Outdated Show resolved Hide resolved

Update docs/source/DEVELOPER.rst

4e93704

Co-authored-by: MekWarrior <[email protected]>

dylanbannon dismissed willgraf’s stale review via 4e93704 August 25, 2020 01:38

touching up text

aee847f

dylanbannon requested a review from MekWarrior August 25, 2020 01:41

MekWarrior approved these changes Aug 25, 2020

View reviewed changes

willgraf self-requested a review August 25, 2020 02:09

willgraf approved these changes Aug 25, 2020

View reviewed changes

vanvalen merged commit 384fb9d into stable Aug 25, 2020

dylanbannon deleted the doc_tweaks_for_paper_resubmission branch August 25, 2020 18:12

willgraf mentioned this pull request Aug 25, 2020

Merge stable into master for release 1.2.1 #372

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Doc tweaks for paper resubmission #374

Doc tweaks for paper resubmission #374

dylanbannon commented Aug 12, 2020 •

edited

Loading

willgraf commented Aug 12, 2020

MekWarrior commented Aug 14, 2020

dylanbannon commented Aug 14, 2020 •

edited

Loading

MekWarrior commented Aug 14, 2020

willgraf commented Aug 14, 2020

dylanbannon commented Aug 14, 2020

dylanbannon commented Aug 14, 2020 •

edited

Loading

willgraf left a comment •

edited

Loading

willgraf left a comment

MekWarrior commented Aug 21, 2020

willgraf commented Aug 21, 2020 •

edited

Loading

willgraf left a comment

MekWarrior left a comment

MekWarrior left a comment

willgraf left a comment

Doc tweaks for paper resubmission #374

Doc tweaks for paper resubmission #374

Conversation

dylanbannon commented Aug 12, 2020 • edited Loading

willgraf commented Aug 12, 2020

MekWarrior commented Aug 14, 2020

dylanbannon commented Aug 14, 2020 • edited Loading

MekWarrior commented Aug 14, 2020

willgraf commented Aug 14, 2020

dylanbannon commented Aug 14, 2020

dylanbannon commented Aug 14, 2020 • edited Loading

willgraf left a comment • edited Loading

Choose a reason for hiding this comment

willgraf left a comment

Choose a reason for hiding this comment

MekWarrior commented Aug 21, 2020

willgraf commented Aug 21, 2020 • edited Loading

willgraf left a comment

Choose a reason for hiding this comment

MekWarrior left a comment

Choose a reason for hiding this comment

MekWarrior left a comment

Choose a reason for hiding this comment

willgraf left a comment

Choose a reason for hiding this comment

dylanbannon commented Aug 12, 2020 •

edited

Loading

dylanbannon commented Aug 14, 2020 •

edited

Loading

dylanbannon commented Aug 14, 2020 •

edited

Loading

willgraf left a comment •

edited

Loading

willgraf commented Aug 21, 2020 •

edited

Loading