Add a visual summary

[nuest]

Suggested by @sje30 on another channel inspired by https://plos.figshare.com/articles/Summary_of_the_10_simple_rules_presented_in_this_paper_/12137772

This might also help us to distill the core 3-5 bullet points out of each rule, so we can reevaluate what can be removed.

I'm open for suggestions how to create this graphic in a useful way, I'd probably go with Inkscape + SVG.

[bdevans]

Good idea! As a starting point, this is my (abbreviated) summary of the rules as they currently stand:

1. Use available tools
2. Use versioned images
3. Format for clarity
4. Document within the Dockerfile
5. Order the instructions
6. Specify software versions
7. Mount user (scripts and) data
8. Make it one-click runnable
9. Use version control and one Dockerfile per project
10. Regularly use and rebuild containers

I'll submit a PR with it as an rmd file (starting with the original headings) so that we can play with reordering and wording under version control.

[sje30]

hi Ben,

This likes a clear and concise summary!

& thanks for all the contribs, haven't been able to follow them all.

Stephen

On Mon, May 04 2020, Ben Evans wrote:

Good idea! As a starting point, this is my (abbreviated) summary of the rules as they currently stand:

1. Use available tools
2. Use versioned images
3. Format for clarity
4. Document within the Dockerfile
5. Order the instructions
6. Specify software versions
7. Mount user (scripts and) data
8. Make it one-click runnable
9. Use version control and one Dockerfile per project
10. Regularly use and rebuild containers

I'll submit a PR with it as an rmd file (starting with the original headings) so that we can play with reordering and wording under version control.

[nuest]

Hi @bdevans ! Do you plan to use draw.io again?

In any case, I'd like to have a copy of the drawing as SVG in the repo as well (open format, don't know about the .drawio one), just to be on the safe side. Leaving this note here to not forget that.

[bdevans]

Yes @nuest that was my intention. It can export to a variety of formats including SVG, so I can add whichever you want.

[nuest]

Perfect! I think with the .drawio in case someone whats to easily make changes, and the .svg for long-term preservation, we should cover all cases.

[nuest]

@bdevans I'd like to have the submission ready version to sign off on by the end of the week. Can you find time to draw before then?

[bdevans]

Hi @nuest, if the new structure is now agreed by all, I'll start on it this evening and should hopefully have it done by the end of the week along with the other minor edits we discussed.

[bdevans]

Ok @nuest, @vsoch, @sje30 et al. here's the work work in progress...

I've iterated on this design quite a few times now so I think it is getting near to a final form but comments are nonetheless welcome :)

[vsoch]

Omg it's beautiful! Is the idea of having the little flag to emulate page markers in a book? I feel like this beautiful graphic justifies printing out little books just so we can do that :) Actually, is that such a crazy idea? This content would be much more easy / fun to digest in a book-like / tutorial format. Maybe a post-publication project?

[bdevans]

Glad you like it! :)

I started with a template which was a more elaborate flag/bookmark, then simplified it but left the arrow-like concavity because I like the way it actively draws the eye in for each point and makes it a bit more dynamic than a flat edge. Also the bookmark thing! :)

I like the idea of the follow-up project though... 🤔

[bdevans]

One point to consider - would you like to add this as a figure in the manuscript? I think the plan was to just use it for advertising on social media but it could make a nice table of contents for the paper too.

[nuest]

This looks awesome @bdevans !

1. Yes, I would like to include it in the paper. Does the "light blue" match the light blue of the current analogy - figure?
2. "Make it one-click runnable"? seems odd in the list now. Maybe "Make the container one click runnable?" or "image" is better?
3. Especially for sharing on social media, but it doesn't hurt to have it in the paper: Can you add a little text at the bottom with a CC-BY license, add your copyright, and add the arXiv identifier DOI for the preprint? People can still cut that part of the image, but I'd like to give it a try to make sure you/we get proper credit.
4. Which icon set did you use?
   • What about a "plug" or "connector" icon for rule 7?
   • The arrows in rule 9 look a bit like "rotate" or "re-do" - what about an up down arrow next to the document? ↕️

---

@vsoch I thought #5 is enough of a follow-up project for me, but the more ways to share the content, the better. You can probably turn the Rmd of the article into a nice website (and PDF, epub) with bookdown pretty quickly...

[bdevans]

Thanks @nuest :) That's useful feedback.

1. I haven't colour matched as I wasn't sure if it was going in the paper but I will make them consistent. Since I'm retouching the analogy figure, I was wondering about swapping the two columns so as you scan from left to right, it goes familiar --> novel. Would that be better or shall I leave it as is?
2. I think "Make the image one-click runnable" might be more accurate than "the container". However, maybe you prefer a looser term like "project" or "Make containers one-click runnable"?
3. Yep, I can add a license and arXiv ID / DOI to the bottom.
4. I mostly used the "office" icons but also a few from elsewhere and I combined a couple in some cases.
   • I tried various options for this but can look for a plug. The gear represents running and cylinder represents the data but then it does double-duty in Rule 2 as the Docker image which I wasn't entirely satisfied with. It's a tricky concept to convey in two colours with only simple elements but I'll see what I can find...! Would it also be better to shorten it to "Mount data at run time"?
   • Good suggestion on the up-down arrow. I'll see how it looks.
   • On the subject of icons, the others I was deliberating about are 6 because it is the actual Git icon and maybe should be more abstract and 10, which gives the idea of a development cycle but I also considered a "home" icon to convey the idea that you should "inhabit" the container on a daily basis.

[bdevans]

Here are some alternatives for the version control icon.

I'm not a licensing expert but if we use the Git logo (or the derivative of it in the middle) then I believe we need to credit Jason Long who designed it and released it under CC-BY 3.0. I don't know if that has to go in the image itself or if adding it to the paper acknowledgements would be enough.

[nuest]

1. Left to right, familiar to novel - sounds good!
2. I am in favour of "image", because, as you say, it is the correct term to use, you cannot run a container. Can you please include the update to the text in the PR for the new figures? Thanks!
3. Great!
4. We should watch out to not be too perfectionist, but some replies
   • For 2, maybe a lock 🔒 ? Because we want to secure a specific version? Or just x.y.z as a text?
   • For 6, we could try to draw a "branching" kind of graph ourselves, see examples
   • I like 10, actually, because it's a good icon for "iterating".
   • So the git one is the only one where we need to worry about the license? The others are CC-0 ? Or do you mean "office icons" from draw.io? I'd assume this one applies for draw.io as well

[bdevans]

1. Ok, will do!
2. Ditto.
3. Done!
4. Yes, that is a danger!
   • I think 2 is ok then if I change 7. I'll try a few more options for 2 and see if adding x.y.z looks ok but it might look a bit too fiddly
   • Ok, I'll have a go at designing a branching VCS icon.
   • I think it's just the Git icon. I'm not sure of the specific license for the draw.io office icons but I found the same statement you did saying that everything is free to use.

I'll aim to upload another draft this evening.

[vsoch]

@nuest when it's totally done, we should do that!

[bdevans]

Ok, how about this?

[bdevans]

Now I look at it again, I think "Build on available images" (or just "Use") would be a better heading for Rule 2 and the text wouldn't need re-working. The previous icon could be used here too. What do you think?

[bdevans]

Here's the reworked "analogy" figure. I've harmonised the colour palette and flattened the overall aesthetic to match the summary figure. Good to go?

[vsoch]

@bdevans you are very good at this! I like it a lot still, very clean and the flat style does indeed match.

[bdevans]

Thanks @vsoch :) The revision history is a good record of how much I've learnt about designing infographics by having a go!

[nuest]

This looks great! Thanks @bdevans !

Continueing in #86