Diagrams sprint

[mrocklin]

We have a few diagrams that have been frequently used in docs, notebooks, slides, and so on. These weren't particularly well made in the past, but they seem to have a great deal of value.

@jrbourbeau and I may choose to sprint on making some more diagrams, in hopes that they improve our level of style, and also increase the impact that we have visually.

I think that there are two questions to answer before this sprint:

1. What diagrams should we make?
2. How should our style look like?

To start conversation, here are two existing drawings by @jrbourbeau , showing the client/scheduler/workers relationship and the collections/graphs/schedulers relationship:

So stylistically we might ask questions like:

1. What is our color palette?
2. What fonts should we use
3. Should we round corners, use bolder lines, ...

In terms of content we might consider the following diagrams (please feel free to edit)

• Client/Scheduler/Worker relationship
• collections -> graph -> schedulers
• What is a Dask worker (thread pool, data storage, connections to other workers, connections to scheduler)
• Decide on a standardized dask array / dask dataframe image (there are a few lying around)
• How does Dask-XGBoost work?
• scikit-learn & distributed joblib (the video https://ml.dask.org/joblib.html has an example diagram)
• Hyperband (prioritizes high-performing models, penalizes poor models. Check @stsievert's paper / scipy talk for an example).
• The value of adaptivity
• Dask Gateway (cc @jcrist)
• Deployment in general. How does Dask relate to Kubernetes/Yarn/Job schedulers, and so on
• Beyond MapReduce. Why dask delayed/futures are valuable
  Slides from Mathew Lodge See 24-27.
• Dask futures and real-time processing
• Maybe something about the dashboard, and how it exposes scheduler state?
  Here is a nice image that mixes a complex scheduler with steampunk
• Something for the Spark comparison page (high pageview count)
• Dask's relationship with GPUs
• Dependency diagram? Maybe there is some way to highlight Xarray/RAPIDS/Prefect/...

I encourage others to add to this list. If you have edit rights please exercise them.

cc @jrbourbeau @TomAugspurger @jcrist @birdsarah (in case you have time to briefly weigh in stylistically on the diagram above)

[jrbourbeau]

Thanks for getting the ball rolling on this @mrocklin! Here are a few thoughts I have regarding diagram styling. Would be interested to hear what others think too.

What is our color palette?

There are a few colors (ref https://marketing.dask.org/en/latest/colors.html) that match the documentation theme that we could also use in diagrams for overall consistency. A couple of thoughts that come to mind are (1) we should choose a non-orange-like color to help show visual distinction where necessary (e.g. collections and schedulers are different objects, so we could make them distinct colors too) and (2) the lighter orange color in those existing diagrams (#fda061) is a little intense and makes me want to squint my eyes

What fonts should we use

FWIW, previously I've used Inconsolata. I like this font because I think it gives things an extra sense of styling and it reminds me of something you might see in terminal or text editor. That said, maybe we want these diagrams to be less distinctive and more familiar. In which case we could consider a more straightforward, cleaner font like Roboto which is used widely on the web (Google designed the font and uses it throughout their material design).

Should we round corners, use bolder lines, ...

Personally, I'm a fan of straight corners, bolder lines, and a slight drop shadow below shapes (like the boxes in the above diagrams)

[mrocklin]

Also cc'ing @jacobtomlinson , who might find this kind of work of interest.

[jacobtomlinson]

As with all design related things consistency is key and having a set of rules to follow is really helpful because I'm generally not very good at remembering this stuff.

What is our color palette?

I am definitely a fan of having a defined secondary color palette. Having the multiple shades of orange is nice as it allows you to break things up a little, but using them to draw clear distinctions may not be great for accessibility as they are very similar. Perhaps having official shades of green, purple or brown would be helpful.

Looking through some corporate brand guidelines there seem to be a few takes on this. Twitter have a selection of blue tinted greys to go with their corporate blue. Netflix seem to have no preference provided the brand red has a 3:1 contrast ratio with the color. Spotify only allow green, black and white, as does Medium. Uber seem to have the widest range of secondary colors with a green, yellow, red, orange, brown and purple.

What fonts should we use

Like both Inconsolata and Roboto. I think the diagrams above look great, especially the second one so my preference would propbably be Inconsolata.

I notice the docs use Lato and the blog uses Helvetica/Arial.

My preference would be to use a different font in diagrams to the body text when they are displayed in documentation and articles. But we should be careful to keep the number of fonts we use to a minimum. Consistency is good.

Should we round corners, use bolder lines, ...

I share @jrbourbeau's preferences for straight corners, bold lines and subtle drop shadows.

---

I also think we should make an effort to create SVG versions of diagrams as well as PNG for backward compatibility. Being able to rescale or edit an SVG makes them easier to reuse in other mediums (presentations, on websites, etc).

[jacobtomlinson]

Perhaps the blue and pink from this diagram are the kind of thing we could include on this palette.

There is also this blue that pops up in other parts of the documentation.

[mrocklin]

I think it's good to be inspired by previous color choices, but I also think that we shouldn't be constrained by them. They were chosen somewhat randomly while I was futzing about in inkscape.

We have relatively few images out there. It should be easy for us to replace all of them with a new color scheme. I would start from the Dask Orange, and then find a good color to complement that.

[mrocklin]

Here is a diagram describing what makes up a Dask Worker: https://docs.google.com/drawings/d/1yAOdTiMrJb3xOSaxZsvW2UOXbWtbgr3EoolEPQ1DxMs/edit?usp=sharing

[mrocklin]

Also, I have to say that Google Drawings is nice, but not as nice as Inkscape. It's probably still a better choice though, just because we can all easily access it.

[mrocklin]

The inconsolata font, or any mono-spaced font, feels either intentionally retro, or unintentionally outdated. Personally I would prefer that we use a non-mono-spaced font.

[mrocklin]

Especially because, I think, that these images will have proportionally more impact on those that are not programmers-first.

[mrocklin]

Here is another: https://docs.google.com/drawings/d/1AoEHphAfhgokORFsh_aZ33bD52Vqx5G2JWcgElk0nzY/edit?usp=sharing

[jacobtomlinson]

I've had a go at putting together some branding guidelines based on the discussion here. It just gives a framework for colors and fonts to work within. The idea is that this should reduce decision fatigue when creating content as you can just draw from this and also ensure some level of consistency.

I've done my best to check color combinations with a contrast checker to ensure they are readable and accessible.

Would be keen to get feedback and iterate on this.

https://docs.google.com/drawings/d/1EGJDwI82qvXZJwD6EKqnqWUsmVYKmQ5TAHSqDzimWu4/edit?usp=sharing

[mrocklin]

Nice! Thanks @jacobtomlinson . Two thoughts:

1. That is a lot of secondary colors.
2. Ideally we have both an orange and a non-orange that work well on light and dark backgrounds. If we look at the gradient in the logo we see that this is true for the oranges (the logo looks good regardless)

[jacobtomlinson]

That is a lot of secondary colors.

Reasonable comment. The top three I took from existing drawings in this thread. The bottom three I generated more intensionally using a palette tool. Green and red have cultural meaning and are often used to denote good/bad, success/failure, etc. I also wanted a darker color which could be displayed as text on a white background (was thinking hyperlinks in documentation specifically with that blue).

Happy to prune back a bit. I think four is a common number of secondary colors to have in a palette.

Ideally we have both an orange and a non-orange that work well on light and dark backgrounds. If we look at the gradient in the logo we see that this is true for the oranges (the logo looks good regardless)

Yes ideally. However none of those oranges meet the W3C accessibility guidelines for text on a white background (they do for graphical objects and user interface components, so are fine in the logo).

We would need something as dark as this for use as text. Which is darker than any element in the logo.

[jcrist]

Not to derail the conversation, but I've also been thinking about trying a dark gray instead of the straight black our current website uses. Black backgrounds often feel too dark and can make things harder to read (I am not a designer, see https://ianstormtaylor.com/design-tip-never-use-black/, https://uxmovement.com/content/why-you-should-never-use-pure-black-for-text-or-backgrounds/, https://graphicdesign.stackexchange.com/questions/25356/why-not-use-pure-black-000-and-pure-white-fff, etc...).

Instead of black, I'd suggest a dark gray e.g. #1d1d1d. Here's our website with this small change:

[jacobtomlinson]

Yeah that's a good point @jcrist.

From one of the things you linked:

You usually want a high contrast between text and its background color. But too high contrast between design elements might give an unsettled and messy impression. Black and white create the highest contrast possible.

The only counterpoint to this is with OLED displays where true black literally means "no light" from the LEDs and therefore #000000 looks much better on those screens, especially in low light situations. One solution to this is to darken your white instead which reduces the contrast between the two.

However ignoring that my preference is for a lighter black rather than a darker white.

[jacobtomlinson]

Here's another version with the lighter blacks.

[jacobtomlinson]

Sorry @mrocklin and @jrbourbeau we are way off track with the Diagrams sprint here, should we move this to another issue?

[mrocklin]

I'm happy either way

…

On Thu, Oct 10, 2019 at 9:11 AM Jacob Tomlinson ***@***.***> wrote: *Sorry @mrocklin <https://github.com/mrocklin> and @jrbourbeau <https://github.com/jrbourbeau> we are way off track with the Diagrams sprint here, should we move this to another issue?* — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#6?email_source=notifications&email_token=AACKZTAP5J3RYKRXSBDOHNLQN4ZYTA5CNFSM4I6UFZ42YY3PNVWWK3TUL52HS4DFVREXG43VMVBW63LNMVXHJKTDN5WW2ZLOORPWSZGOEA4P5HA#issuecomment-540606108>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AACKZTEQP7MLWDFROPCSJU3QN4ZYTANCNFSM4I6UFZ4Q> .

[mrocklin]

I'm mostly just excited that we have a bunch of computational science people talking about colors :)

…

On Thu, Oct 10, 2019 at 9:15 AM Matthew Rocklin ***@***.***> wrote: I'm happy either way On Thu, Oct 10, 2019 at 9:11 AM Jacob Tomlinson ***@***.***> wrote: > *Sorry @mrocklin <https://github.com/mrocklin> and @jrbourbeau > <https://github.com/jrbourbeau> we are way off track with the Diagrams > sprint here, should we move this to another issue?* > > — > You are receiving this because you were mentioned. > Reply to this email directly, view it on GitHub > <#6?email_source=notifications&email_token=AACKZTAP5J3RYKRXSBDOHNLQN4ZYTA5CNFSM4I6UFZ42YY3PNVWWK3TUL52HS4DFVREXG43VMVBW63LNMVXHJKTDN5WW2ZLOORPWSZGOEA4P5HA#issuecomment-540606108>, > or unsubscribe > <https://github.com/notifications/unsubscribe-auth/AACKZTEQP7MLWDFROPCSJU3QN4ZYTANCNFSM4I6UFZ4Q> > . >

[jcrist]

I personally prefer the #1D1D1D background. I'm happy to update the sphinx theme accordingly if I get the go-ahead. Also happy to open a new issue for this.

[mrocklin]

@jrbourbeau want to set some time aside tomorrow to make some diagrams together? Establishing style ahead of time is ideal, but we can also modify things easily after the fact.

[TomAugspurger]

Here's a joblib / dask prototype

https://docs.google.com/drawings/d/1tWbey77qTozMrBenAOcjTFjpm2VIj0Gy0unHk5b5idc/edit?usp=sharing

[jrbourbeau]

As discussed in the maintainer call yesterday, we're going to meet tomorrow (Oct 17) to make some diagrams (woo!). Let's meet in https://whereby.com/dask-dev from 8 AM - 12 PM central time (14:00 - 18:00 in the UK I think). Anyone who would like to participate should feel free to join for whatever portion of time you're available.

[TomAugspurger]

Did the topic of different backgrounds come up yesterday? Say I have a diagram I'd like to use on both docs.dask.org (light background) and in the Dask slide deck (dark background). Is there an easy way to do that without too much duplication?

[jacobtomlinson]

Yeah it came up. I think the plan was to provide both, at least for highly used diagrams.

[jsignell]

I just used the colors provided in #6 (comment) in dask/dask#5965. Should that branding image be added to https://marketing.dask.org. Or is it already and I just didn't find it?

[jrbourbeau]

Moving to marketing.dask.org sounds good to me. Currently I think the style guide hasn't moved outside of the issue you linked to @jsignell. Perhaps the "Style and Colors" page is a natural place for it