The document discusses using Markdown as a simple tool for writing documents and maintaining research projects. Markdown provides benefits over other document tools like Microsoft Word by being simpler, easier to collaborate on, and better for version control. It also helps with reproducible research by making data, code, and content easily shareable. While Markdown lacks some advanced formatting options, its flexibility allows it to cover most documentation needs with less complexity compared to other tools.

1. Take it easy with markdown
NGI Wednesday Seminar Talk
Lukasz K Bonenberg
1

2. Introduction
2

3. 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

4. Latex vs Word
Figure 1: Word or Latex 4

5. Latex perception
Figure 2: Complex but worth it 5

6. Microsoft Office perception
Figure 3: An Efficiency Comparison of Document Preparation Systems
Used in Academic Research and Development
6

7. Re-framing the question
7

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

9. Does content matters?
Figure 4: Content is king
9

10. Who send what?
Figure 5: Entropy builds up 10

11. 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

12. Sum of all parts
Figure 6: How easy is to maintain document
12

13. Tools
13

14. Markdown - Keep it simple
Figure 7: https://daringfireball.net/projects/markdown/ 14

15. One to rule them all
Figure 8: http: // pandoc. org/
15

16. Control the time
Figure 9: How good is your version control? 16

17. Some downsides
17

18. 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

19. How many tools are we using?
Figure 10: complexity vs effort
19

20. Markdown - it’s too flexible
Figure 11: Spoil for choice? 20

21. Some upsides
21

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

23. Maintaining research
The 2014 Good Enough Practices in Scientific Computing paper
highlight need for:
• Data Management
• Software management
• Collaboration + project management
23

24. Maintaining research
Reproducible research - scientific claims, are published with their
data and software code so that others may verify the findings and
build 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

25. Open Source
Figure 13: Power of many
25

26. Examples
26

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

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

29. Social aspect
Figure 16: https://rpubs.com/ykashou92/eq_wmap
• Hawkers in Singapore
• interactive plots
29

30. Big guys do it
Figure 17 30

31. Summary
31

32. 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

33. useful links
• Try markdown online
• Pandoc
• try online
• check demos
• http://www.sphinx-doc.org
• git
• guide
• try yourself
• R
• RMarkdown
• ioslides
• knit
33

34. 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