Take it easy with markdownNGI Wednesday Seminar Talk

Lukasz K Bonenberg

1

Introduction

2

Questionnaire results

• Most interest in:• general understanding• making presentation

• why would I use those tools instead of MS Office?• everybody use Microsoft Office or equivalent

• Latex and git reasonably known• Markdown not known

3

Latex vs Word

Figure 1: Word or Latex 4

Latex perception

Figure 2: Complex but worth it 5

Microsoft Office perception

Figure 3: An Efficiency Comparison of Document Preparation SystemsUsed in Academic Research and Development

6

Re-framing the question

7

Change

• Change for the sake of change is rarely a sensible use of time.• Tools have to fit the purpose.

8

Does content matters?

Figure 4: Content is king

9

Who send what?

Figure 5: Entropy builds up 10

Which is my latest copy?

• report_01.doc• report_02.doc• report_03_revByJim.doc• report_04_changes.doc• report_05_final.doc• report_05_finalFinal.doc• report_05_finalFinal_FINAL.doc• report_05_finalFinal_FINAL_send.doc

11

Sum of all parts

Figure 6: How easy is to maintain document

12

Tools

13

Markdown - Keep it simple

Figure 7: https://daringfireball.net/projects/markdown/ 14

One to rule them all

Figure 8: http: // pandoc. org/

15

Control the time

Figure 9: How good is your version control? 16

Some downsides

17

Change

• Change for the sake of change is rarely a sensible use of time.• How are we going to interact with others?

• Tools have to fit the purpose.• How many tools do I need to learn?• Who maintain those tools?

18

How many tools are we using?

Figure 10: complexity vs effort

19

Markdown - it’s too flexible

Figure 11: Spoil for choice? 20

Some upsides

21

Deep Work

Figure 12: http: // calnewport. com/ books/ deep-work/ 22

Maintaining research

The 2014 Good Enough Practices in Scientific Computing paperhighlight need for:

• Data Management• Software management• Collaboration + project management

23

Maintaining research

Reproducible research - scientific claims, are published with theirdata and software code so that others may verify the findings andbuild upon them1.

Examples:

• Gravitational Wave - http://bit.ly/LIGO_OS• Stanford Exploration Project -

http://sepwww.stanford.edu/• West Virginia University’s Computer vision Lab -

http://www.csee.wvu.edu/~xinl/• open source papers - http://bit.ly/1MbL6C9

1Roger Peng, Johns Hopkins University

24

Open Source

Figure 13: Power of many

25

Examples

26

Team work

Figure 14: https: // www. atlassian. com/ git/ tutorials/ 27

Auto-grading using git

Figure 15: Sebastien Saunier’s auto-grader http: // bit. ly/ 1MQLSo9 28

Social aspect

Figure 16: https://rpubs.com/ykashou92/eq_wmap

• Hawkers in Singapore• interactive plots

29

Big guys do it

Figure 17 30

Summary

31

Take away notes

• There is a need for reproducible research• Markdown is one of 20-80 tools - it will cover most of problems

with a small effort• content beats visuals• data management and fidelity is important• set of small dedicated tools allows for better flexibility and low

entropy

32

useful links

• Try markdown online• Pandoc

• try online• check demos• http://www.sphinx-doc.org

• git• guide• try yourself

• R• RMarkdown• ioslides• knit

33

Thank you

I hope you learn something new today.

It would be great to get feedback at http://bit.ly/LKB_FB.

Code is at https://github.com/DfAC/NottinghamR_Markdown.

34