Drake: Add "pitch" vignette

[krlmlr]

• use slides as internal article for pkgdown, https://github.com/krlmlr/drake-pitch
• add words and links to further reading, use this as "Get started" vignette
• think about adapting the cooking slides, https://github.com/krlmlr/cooking

[wlandau]

Yes, this should definitely replace the drake.Rmd vignette and the Get Started page. Right now, it just copies the basic example.

[wlandau]

@krlmlr could I delegate this one to you?

[wlandau]

I thought this might be nice to have in 5.1.0, but we can absolutely postpone it. Thoughts?

[krlmlr]

I can take a stab next week, but not much earlier. Happy to postpone.

[wlandau]

Sure, no urgency here. Removing from the 5.1.0 milestone.

[lorenzwalthert]

Just stumbled upon that. I feel like the basic example vignette is already quite complicated and I think it would be beneficial to have a more basic example to get people started. From looking at the basic example for about 10 minutes, I did not understand the core of drake, because IMHO it tries to do too much. I only understood the basic mechanisms after looking at the slides linked above by @krlmlr.

[wlandau]

I hear you. That was the first vignette I ever wrote for drake, and when I created it, I felt like I needed to demonstrate all the main features. I plan to make it look more like the gsp and cranlogs vignettes. Same goes for the analogous pedagogical drake_example()'s.

The main two things on my mind for drake right now are parallel efficiency and documentation. It's just a matter of finding enough time.

[wlandau]

The "pitch" vignette proposed in this issue will replace the existing drake.Rmd vignette (also the Get Started page). I also plan to pair it with another pedagogical drake_example().

[lorenzwalthert]

ok, cool. Thanks @wlandau, I appreciate your work on drake.

[wlandau]

The documentation is much improved now. There is a new drake_example("main") based on Kirill's slides, and it is front and center in the README, the drake.Rmd vignette, and the Get Started page. The old "basic example" is renamed the "mtcars example". I will make an announcement early this week. Thanks again for the nudge.

[lorenzwalthert]

That's awesome.

[krlmlr]

Thanks for taking care of it! I like the simple language, and the brevity of the presentation. Just very minor remarks:

• "make() to actually make" sounds a bit odd, I sometimes frame this like "...to perform the computation" but maybe there's a shorter and more fitting expression.
• "You will make mistakes" sounds pessimistic, maybe "After a while you'll notice potential for improvement" or even "Don't worry about mistakes, you can always go back"

[krlmlr]

Also, I forgot to credit Jenny's slide in my slide deck, could you please add a link to https://speakerdeck.com/jennybc/zen-and-the-art-of-workflow-maintenance?slide=55?

CC @jennybc.

[wlandau]

Gosh, those comments make such a difference! See 617500fc7a13ebe6f89c752c9ab69639ffa95e9b. I tweaked the language and changed the attribution from you to Jenny.