Tips and advice when creating a python software for lab members to use in academia

class: middle, center, inverse

# Tips and advice when creating a python software for lab members to use in academia

.pull-left[
<img src="images/business-team.jpg" width="70%" style="display: block; margin: auto;" />

### PyData Global 2021
]

.pull-right[
<img src="images/books.jpg" width="70%" style="display: block; margin: auto;" />

### Jeremy Selva [<svg aria-hidden="true" role="img" viewBox="0 0 496 512" style="height:1em;width:0.97em;vertical-align:-0.125em;margin-left:auto;margin-right:auto;font-size:inherit;fill:currentColor;overflow:visible;position:relative;"><path d="M165.9 397.4c0 2-2.3 3.6-5.2 3.6-3.3.3-5.6-1.3-5.6-3.6 0-2 2.3-3.6 5.2-3.6 3-.3 5.6 1.3 5.6 3.6zm-31.1-4.5c-.7 2 1.3 4.3 4.3 4.9 2.6 1 5.6 0 6.2-2s-1.3-4.3-4.3-5.2c-2.6-.7-5.5.3-6.2 2.3zm44.2-1.7c-2.9.7-4.9 2.6-4.6 4.9.3 2 2.9 3.3 5.9 2.6 2.9-.7 4.9-2.6 4.6-4.6-.3-1.9-3-3.2-5.9-2.9zM244.8 8C106.1 8 0 113.3 0 252c0 110.9 69.8 205.8 169.5 239.2 12.8 2.3 17.3-5.6 17.3-12.1 0-6.2-.3-40.4-.3-61.4 0 0-70 15-84.7-29.8 0 0-11.4-29.1-27.8-36.6 0 0-22.9-15.7 1.6-15.4 0 0 24.9 2 38.6 25.8 21.9 38.6 58.6 27.5 72.9 20.9 2.3-16 8.8-27.1 16-33.7-55.9-6.2-112.3-14.3-112.3-110.5 0-27.5 7.6-41.3 23.6-58.9-2.6-6.5-11.1-33.3 2.6-67.9 20.9-6.5 69 27 69 27 20-5.6 41.5-8.5 62.8-8.5s42.8 2.9 62.8 8.5c0 0 48.1-33.6 69-27 13.7 34.7 5.2 61.4 2.6 67.9 16 17.7 25.8 31.5 25.8 58.9 0 96.5-58.9 104.2-114.8 110.5 9.2 7.9 17 22.9 17 46.4 0 33.7-.3 75.4-.3 83.6 0 6.5 4.6 14.4 17.3 12.1C428.2 457.8 496 362.9 496 252 496 113.3 383.5 8 244.8 8zM97.2 352.9c-1.3 1-1 3.3.7 5.2 1.6 1.6 3.9 2.3 5.2 1 1.3-1 1-3.3-.7-5.2-1.6-1.6-3.9-2.3-5.2-1zm-10.8-8.1c-.7 1.3.3 2.9 2.3 3.9 1.6 1 3.6.7 4.3-.7.7-1.3-.3-2.9-2.3-3.9-2-.6-3.6-.3-4.3.7zm32.4 35.6c-1.6 1.3-1 4.3 1.3 6.2 2.3 2.3 5.2 2.6 6.5 1 1.3-1.3.7-4.3-1.3-6.2-2.2-2.3-5.2-2.6-6.5-1zm-11.4-14.7c-1.6 1-1.6 3.6 0 5.9 1.6 2.3 4.3 3.3 5.6 2.3 1.6-1.3 1.6-3.9 0-6.2-1.4-2.3-4-3.3-5.6-2z"/></svg>](https://github.com/JauntyJJS) [<svg aria-hidden="true" role="img" viewBox="0 0 448 512" style="height:1em;width:0.88em;vertical-align:-0.125em;margin-left:auto;margin-right:auto;font-size:inherit;fill:currentColor;overflow:visible;position:relative;"><path d="M416 32H31.9C14.3 32 0 46.5 0 64.3v383.4C0 465.5 14.3 480 31.9 480H416c17.6 0 32-14.5 32-32.3V64.3c0-17.8-14.4-32.3-32-32.3zM135.4 416H69V202.2h66.5V416zm-33.2-243c-21.3 0-38.5-17.3-38.5-38.5S80.9 96 102.2 96c21.2 0 38.5 17.3 38.5 38.5 0 21.3-17.2 38.5-38.5 38.5zm282.1 243h-66.4V312c0-24.8-.5-56.7-34.5-56.7-34.6 0-39.9 27-39.9 54.9V416h-66.4V202.2h63.7v29.2h.9c8.9-16.8 30.6-34.5 62.9-34.5 67.2 0 79.7 44.3 79.7 101.9V416z"/></svg>](https://www.linkedin.com/in/jeremy-selva-085b9112a/) [<svg aria-hidden="true" role="img" viewBox="0 0 512 512" style="height:1em;width:1em;vertical-align:-0.125em;margin-left:auto;margin-right:auto;font-size:inherit;fill:currentColor;overflow:visible;position:relative;"><path d="M326.612 185.391c59.747 59.809 58.927 155.698.36 214.59-.11.12-.24.25-.36.37l-67.2 67.2c-59.27 59.27-155.699 59.262-214.96 0-59.27-59.26-59.27-155.7 0-214.96l37.106-37.106c9.84-9.84 26.786-3.3 27.294 10.606.648 17.722 3.826 35.527 9.69 52.721 1.986 5.822.567 12.262-3.783 16.612l-13.087 13.087c-28.026 28.026-28.905 73.66-1.155 101.96 28.024 28.579 74.086 28.749 102.325.51l67.2-67.19c28.191-28.191 28.073-73.757 0-101.83-3.701-3.694-7.429-6.564-10.341-8.569a16.037 16.037 0 0 1-6.947-12.606c-.396-10.567 3.348-21.456 11.698-29.806l21.054-21.055c5.521-5.521 14.182-6.199 20.584-1.731a152.482 152.482 0 0 1 20.522 17.197zM467.547 44.449c-59.261-59.262-155.69-59.27-214.96 0l-67.2 67.2c-.12.12-.25.25-.36.37-58.566 58.892-59.387 154.781.36 214.59a152.454 152.454 0 0 0 20.521 17.196c6.402 4.468 15.064 3.789 20.584-1.731l21.054-21.055c8.35-8.35 12.094-19.239 11.698-29.806a16.037 16.037 0 0 0-6.947-12.606c-2.912-2.005-6.64-4.875-10.341-8.569-28.073-28.073-28.191-73.639 0-101.83l67.2-67.19c28.239-28.239 74.3-28.069 102.325.51 27.75 28.3 26.872 73.934-1.155 101.96l-13.087 13.087c-4.35 4.35-5.769 10.79-3.783 16.612 5.864 17.194 9.042 34.999 9.69 52.721.509 13.906 17.454 20.446 27.294 10.606l37.106-37.106c59.271-59.259 59.271-155.699.001-214.959z"/></svg>](https://jeremy-selva.netlify.app/) [<svg aria-hidden="true" role="img" viewBox="0 0 512 512" style="height:1em;width:1em;vertical-align:-0.125em;margin-left:auto;margin-right:auto;font-size:inherit;fill:currentColor;overflow:visible;position:relative;"><path d="M459.37 151.716c.325 4.548.325 9.097.325 13.645 0 138.72-105.583 298.558-298.558 298.558-59.452 0-114.68-17.219-161.137-47.106 8.447.974 16.568 1.299 25.34 1.299 49.055 0 94.213-16.568 130.274-44.832-46.132-.975-84.792-31.188-98.112-72.772 6.498.974 12.995 1.624 19.818 1.624 9.421 0 18.843-1.3 27.614-3.573-48.081-9.747-84.143-51.98-84.143-102.985v-1.299c13.969 7.797 30.214 12.67 47.431 13.319-28.264-18.843-46.781-51.005-46.781-87.391 0-19.492 5.197-37.36 14.294-52.954 51.655 63.675 129.3 105.258 216.365 109.807-1.624-7.797-2.599-15.918-2.599-24.04 0-57.828 46.782-104.934 104.934-104.934 30.213 0 57.502 12.67 76.67 33.137 23.715-4.548 46.456-13.32 66.599-25.34-7.798 24.366-24.366 44.833-46.132 57.827 21.117-2.273 41.584-8.122 60.426-16.243-14.292 20.791-32.161 39.308-52.628 54.253z"/></svg>](https://twitter.com/JauntyJJS)

]

.left[
.footnote[
Images by [Amonrat Rungreangfangsai](https://www.vecteezy.com/members/amy1313)

[Xaringan](https://github.com/yihui/xaringan) Slide Template by [Sharla Gelfand](https://github.com/sharlagelfand/sharstudioconf) [<svg aria-hidden="true" role="img" viewBox="0 0 496 512" style="height:1em;width:0.97em;vertical-align:-0.125em;margin-left:auto;margin-right:auto;font-size:inherit;fill:currentColor;overflow:visible;position:relative;"><path d="M165.9 397.4c0 2-2.3 3.6-5.2 3.6-3.3.3-5.6-1.3-5.6-3.6 0-2 2.3-3.6 5.2-3.6 3-.3 5.6 1.3 5.6 3.6zm-31.1-4.5c-.7 2 1.3 4.3 4.3 4.9 2.6 1 5.6 0 6.2-2s-1.3-4.3-4.3-5.2c-2.6-.7-5.5.3-6.2 2.3zm44.2-1.7c-2.9.7-4.9 2.6-4.6 4.9.3 2 2.9 3.3 5.9 2.6 2.9-.7 4.9-2.6 4.6-4.6-.3-1.9-3-3.2-5.9-2.9zM244.8 8C106.1 8 0 113.3 0 252c0 110.9 69.8 205.8 169.5 239.2 12.8 2.3 17.3-5.6 17.3-12.1 0-6.2-.3-40.4-.3-61.4 0 0-70 15-84.7-29.8 0 0-11.4-29.1-27.8-36.6 0 0-22.9-15.7 1.6-15.4 0 0 24.9 2 38.6 25.8 21.9 38.6 58.6 27.5 72.9 20.9 2.3-16 8.8-27.1 16-33.7-55.9-6.2-112.3-14.3-112.3-110.5 0-27.5 7.6-41.3 23.6-58.9-2.6-6.5-11.1-33.3 2.6-67.9 20.9-6.5 69 27 69 27 20-5.6 41.5-8.5 62.8-8.5s42.8 2.9 62.8 8.5c0 0 48.1-33.6 69-27 13.7 34.7 5.2 61.4 2.6 67.9 16 17.7 25.8 31.5 25.8 58.9 0 96.5-58.9 104.2-114.8 110.5 9.2 7.9 17 22.9 17 46.4 0 33.7-.3 75.4-.3 83.6 0 6.5 4.6 14.4 17.3 12.1C428.2 457.8 496 362.9 496 252 496 113.3 383.5 8 244.8 8zM97.2 352.9c-1.3 1-1 3.3.7 5.2 1.6 1.6 3.9 2.3 5.2 1 1.3-1 1-3.3-.7-5.2-1.6-1.6-3.9-2.3-5.2-1zm-10.8-8.1c-.7 1.3.3 2.9 2.3 3.9 1.6 1 3.6.7 4.3-.7.7-1.3-.3-2.9-2.3-3.9-2-.6-3.6-.3-4.3.7zm32.4 35.6c-1.6 1.3-1 4.3 1.3 6.2 2.3 2.3 5.2 2.6 6.5 1 1.3-1.3.7-4.3-1.3-6.2-2.2-2.3-5.2-2.6-6.5-1zm-11.4-14.7c-1.6 1-1.6 3.6 0 5.9 1.6 2.3 4.3 3.3 5.6 2.3 1.6-1.3 1.6-3.9 0-6.2-1.4-2.3-4-3.3-5.6-2z"/></svg>](https://github.com/sharlagelfand) [<svg aria-hidden="true" role="img" viewBox="0 0 512 512" style="height:1em;width:1em;vertical-align:-0.125em;margin-left:auto;margin-right:auto;font-size:inherit;fill:currentColor;overflow:visible;position:relative;"><path d="M326.612 185.391c59.747 59.809 58.927 155.698.36 214.59-.11.12-.24.25-.36.37l-67.2 67.2c-59.27 59.27-155.699 59.262-214.96 0-59.27-59.26-59.27-155.7 0-214.96l37.106-37.106c9.84-9.84 26.786-3.3 27.294 10.606.648 17.722 3.826 35.527 9.69 52.721 1.986 5.822.567 12.262-3.783 16.612l-13.087 13.087c-28.026 28.026-28.905 73.66-1.155 101.96 28.024 28.579 74.086 28.749 102.325.51l67.2-67.19c28.191-28.191 28.073-73.757 0-101.83-3.701-3.694-7.429-6.564-10.341-8.569a16.037 16.037 0 0 1-6.947-12.606c-.396-10.567 3.348-21.456 11.698-29.806l21.054-21.055c5.521-5.521 14.182-6.199 20.584-1.731a152.482 152.482 0 0 1 20.522 17.197zM467.547 44.449c-59.261-59.262-155.69-59.27-214.96 0l-67.2 67.2c-.12.12-.25.25-.36.37-58.566 58.892-59.387 154.781.36 214.59a152.454 152.454 0 0 0 20.521 17.196c6.402 4.468 15.064 3.789 20.584-1.731l21.054-21.055c8.35-8.35 12.094-19.239 11.698-29.806a16.037 16.037 0 0 0-6.947-12.606c-2.912-2.005-6.64-4.875-10.341-8.569-28.073-28.073-28.191-73.639 0-101.83l67.2-67.19c28.239-28.239 74.3-28.069 102.325.51 27.75 28.3 26.872 73.934-1.155 101.96l-13.087 13.087c-4.35 4.35-5.769 10.79-3.783 16.612 5.864 17.194 9.042 34.999 9.69 52.721.509 13.906 17.454 20.446 27.294 10.606l37.106-37.106c59.271-59.259 59.271-155.699.001-214.959z"/></svg>](https://sharla.online) [<svg aria-hidden="true" role="img" viewBox="0 0 512 512" style="height:1em;width:1em;vertical-align:-0.125em;margin-left:auto;margin-right:auto;font-size:inherit;fill:currentColor;overflow:visible;position:relative;"><path d="M459.37 151.716c.325 4.548.325 9.097.325 13.645 0 138.72-105.583 298.558-298.558 298.558-59.452 0-114.68-17.219-161.137-47.106 8.447.974 16.568 1.299 25.34 1.299 49.055 0 94.213-16.568 130.274-44.832-46.132-.975-84.792-31.188-98.112-72.772 6.498.974 12.995 1.624 19.818 1.624 9.421 0 18.843-1.3 27.614-3.573-48.081-9.747-84.143-51.98-84.143-102.985v-1.299c13.969 7.797 30.214 12.67 47.431 13.319-28.264-18.843-46.781-51.005-46.781-87.391 0-19.492 5.197-37.36 14.294-52.954 51.655 63.675 129.3 105.258 216.365 109.807-1.624-7.797-2.599-15.918-2.599-24.04 0-57.828 46.782-104.934 104.934-104.934 30.213 0 57.502 12.67 76.67 33.137 23.715-4.548 46.456-13.32 66.599-25.34-7.798 24.366-24.366 44.833-46.132 57.827 21.117-2.273 41.584-8.122 60.426-16.243-14.292 20.791-32.161 39.308-52.628 54.253z"/></svg>](https://twitter.com/sharlagelfand) [<svg aria-hidden="true" role="img" viewBox="0 0 448 512" style="height:1em;width:0.88em;vertical-align:-0.125em;margin-left:auto;margin-right:auto;font-size:inherit;fill:currentColor;overflow:visible;position:relative;"><path d="M186.8 202.1l95.2 54.1-95.2 54.1V202.1zM448 80v352c0 26.5-21.5 48-48 48H48c-26.5 0-48-21.5-48-48V80c0-26.5 21.5-48 48-48h352c26.5 0 48 21.5 48 48zm-42 176.3s0-59.6-7.6-88.2c-4.2-15.8-16.5-28.2-32.2-32.4C337.9 128 224 128 224 128s-113.9 0-142.2 7.7c-15.7 4.2-28 16.6-32.2 32.4-7.6 28.5-7.6 88.2-7.6 88.2s0 59.6 7.6 88.2c4.2 15.8 16.5 27.7 32.2 31.9C110.1 384 224 384 224 384s113.9 0 142.2-7.7c15.7-4.2 28-16.1 32.2-31.9 7.6-28.5 7.6-88.1 7.6-88.1z"/></svg>](https://www.youtube.com/watch?v=JThd3YYQXGg)
]
]

.center[.footnote[https://jauntyjjs.github.io/PyDataGlobal2021Talk [<svg aria-hidden="true" role="img" viewBox="0 0 384 512" style="height:1em;width:0.75em;vertical-align:-0.125em;margin-left:auto;margin-right:auto;font-size:inherit;fill:currentColor;overflow:visible;position:relative;"><path d="M181.9 256.1c-5-16-4.9-46.9-2-46.9 8.4 0 7.6 36.9 2 46.9zm-1.7 47.2c-7.7 20.2-17.3 43.3-28.4 62.7 18.3-7 39-17.2 62.9-21.9-12.7-9.6-24.9-23.4-34.5-40.8zM86.1 428.1c0 .8 13.2-5.4 34.9-40.2-6.7 6.3-29.1 24.5-34.9 40.2zM248 160h136v328c0 13.3-10.7 24-24 24H24c-13.3 0-24-10.7-24-24V24C0 10.7 10.7 0 24 0h200v136c0 13.2 10.8 24 24 24zm-8 171.8c-20-12.2-33.3-29-42.7-53.8 4.5-18.5 11.6-46.6 6.2-64.2-4.7-29.4-42.4-26.5-47.8-6.8-5 18.3-.4 44.1 8.1 77-11.6 27.6-28.7 64.6-40.8 85.8-.1 0-.1.1-.2.1-27.1 13.9-73.6 44.5-54.5 68 5.6 6.9 16 10 21.5 10 17.9 0 35.7-18 61.1-61.8 25.8-8.5 54.1-19.1 79-23.2 21.7 11.8 47.1 19.5 64 19.5 29.2 0 31.2-32 19.7-43.4-13.9-13.6-54.3-9.7-73.6-7.2zM377 105L279 7c-4.5-4.5-10.6-7-17-7h-6v128h128v-6.1c0-6.3-2.5-12.4-7-16.9zm-74.1 255.3c4.1-2.7-2.5-11.9-42.8-9 37.1 15.8 42.8 9 42.8 9z"/></svg>](https://jauntyjjs.github.io/PyDataGlobal2021Talk/PyDataGlobal2021Talk.pdf)]
]

---
## Introduction

It started with a Python script used to organise Mass Spectrometry data for my project.

## Introduction

Many asked me to troubleshoot R/Python/Bash scripts, created by past collaborators, that were meant to do similar tasks as mine.
- *"This script does not work on my computer anymore. I don't know why."* 😵

.pull-left[

]

.pull-right[

]

.left[.footnote[Images by [Amonrat Rungreangfangsai](https://www.vecteezy.com/members/amy1313)]]

---

## Introduction

I combined all these scripts into one Windows executable software in Python called [MSOrganiser](https://github.com/SLINGhub/MSOrganiser).

.pull-left[
<img src="images/many-scripts.jpg" width="100%" style="display: block; margin: auto;" />
]

.pull-right[

.center[
https://github.com/SLINGhub/MSOrganiser
]

]

.left[.footnote[Images by [Amonrat Rungreangfangsai](https://www.vecteezy.com/members/amy1313)]]

---

## Introduction

Looking back, I realise that things have not been easy...

.left[.footnote[Images by [Amonrat Rungreangfangsai](https://www.vecteezy.com/members/amy1313)]]

## Introduction

In academia, most of us are not trained in coding or software development. It is hard for us to write software for our own research paper, it is even more challenging to create software for others to use.

.pull-left[

Daniel Lemire’s [blog](https://lemire.me/blog/2012/06/18/on-the-quality-of-academic-software/)

<img src="images/Daniel_Lemire_Blog.jpg" width="80%" style="display: block; margin: auto;" />
]

.pull-right[

]

.left[.footnote[Images by [Amonrat Rungreangfangsai](https://www.vecteezy.com/members/amy1313)]]

---

## Introduction

In this talk, I decide to share some things that have helped me tremendously.

.left[.footnote[Images by [Amonrat Rungreangfangsai](https://www.vecteezy.com/members/amy1313)]]

---
## 1: Convert scripts to a web service or executable software

Users make less error when clicking buttons compared to typing in command lines

---

## Advice 1 Tips

- Chriskiehl's [Gooey](https://github.com/chriskiehl/Gooey) to create a simple GUI interface quickly.

- [Pyinstaller](https://www.pyinstaller.org/) to convert the scripts to a stand alone executable program.

---
## Advice 1 Tips

Jack McKew's [blog](https://jackmckew.dev/making-executable-guis-with-python-gooey-pyinstaller.html) helps me make use of the two tools to get what I need.

<br>

---

## I forgot about new users

.left[.footnote[
Baby Dragon by [drawinghowtos.com](https://drawinghowtos.com/baby-dragon-2-7909)

Cartoon Hydra by [how-to-draw-cartoons-online.com](https://how-to-draw-cartoons-online.com/cartoon-hydra.html)
]
]

---

## I forgot about new users

New users typical reaction to complex program
- Scared 🥺 and Confused 😵
- *"Maybe this tool is not for me"* 😂

.pull-left[
<img src="images/cartoon_hydra.gif" width="65%" style="display: block; margin: auto;" />
]

.pull-right[
<img src="images/scared.jpg" width="80%" style="display: block; margin: auto;" />
]

.left[.footnote[
Cartoon Hydra by [how-to-draw-cartoons-online.com](https://how-to-draw-cartoons-online.com/cartoon-hydra.html)

Images by [Amonrat Rungreangfangsai](https://www.vecteezy.com/members/amy1313)]]

---
## 2: Give a software overview using cheatsheet

RStudio cheatsheet [examples](https://www.rstudio.com/resources/cheatsheets/)
and [template](https://github.com/rstudio/cheatsheets/blob/master/.github/CONTRIBUTING.md) and [advice](https://github.com/rstudio/cheatsheets/blob/master/README.md)

.pull-left[
<img src="images/RStudio_cheatsheet_examples.jpg" width="100%" style="display: block; margin: auto;" />
]

.pull-right[
<img src="images/RStudio_cheatsheet.jpg" width="100%" style="display: block; margin: auto;" />
]

## 3: Provide helpful messages when users make a mistake

Users and programmers make mistakes sometimes. Software error messages are unavoidable.

.pull-left[
<img src="images/unknown_error.jpg" width="90%" style="display: block; margin: auto;" />
]

.pull-right[
<img src="images/hammer-computer.jpg" width="100%" style="display: block; margin: auto;" />
]

.left[.footnote[Images by [Amonrat Rungreangfangsai](https://www.vecteezy.com/members/amy1313)]]

## 3: Provide helpful messages when users make a mistake

However, if you can make them helpful, it does goes a long way.

.pull-left[

<img src="images/helpful_error.jpg" width="60%" style="display: block; margin: auto;" />
]

.pull-right[
<img src="images/thumbs-up.jpg" width="100%" style="display: block; margin: auto;" />
]

.left[.footnote[Images by [Amonrat Rungreangfangsai](https://www.vecteezy.com/members/amy1313)]]

## Advice 3 Tips 
.pull-left[
Saadia Minhas' [blog](https://uxplanet.org/how-to-write-good-error-messages-858e4551cd4) provides some good tips

<img src="images/saadia-minhas-blog.jpg" width="90%" style="display: block; margin: auto;" />
]

.pull-right[
Micheal Lynch's [tip](https://mtlynch.io/code-review-love/) to show openness to criticism
 
<img src="images/michael-lynch-blog.jpg" width="100%" style="display: block; margin: auto;" />
]

## 4: Include necessary software reports to show reliability

Academia journals are getting more demanding with regards to software, wanting reusability besides reproducibility.

.pull-left[
<img src="images/nature-reusable-1.jpg" width="90%" style="display: block; margin: auto;" />
]

.pull-right[
<img src="images/nature-reusable-2.jpg" width="100%" style="display: block; margin: auto;" />
]

https://www.nature.com/articles/s43588-021-00109-9

## Advice 4 Tips

Tag a label on different software version and encourage users to cite not just the software name but the version number as well.

## Advice 4 Tips

Create a report file/table (pdf or excel) that store the user's input parameters

.pull-left[
<img src="images/report-MSOrganiser.jpg" width="90%" style="display: block; margin: auto;" />
]

.pull-right[

Chris Moffitt's [example](https://pbpython.com/pdf-reports.html) using WeasyPrint

Matt Clarke's [example](https://practicaldatascience.co.uk/data-science/how-to-create-pdf-reports-in-python-using-pandas-and-gilfoyle) using Gilfoyle

<img src="images/report-Matt-Clarke.jpg" width="90%" style="display: block; margin: auto;" />
]

## Advice 4 Tips

Show pre-processing results to explain how the software calculate the final results.

They are helpful when there is a need to troubleshoot for logical errors

## My documentation issue

I started my documentation by trying to follow some advice provided by Lee's [article](https://journals.plos.org/ploscompbiol/article?id=10.1371/journal.pcbi.1006561)

## My documentation issue

As my documentation starts to get longer and more complex, people find it hard to understand.

.pull-left[

<img src="images/documentation-confused.jpg" width="100%" style="display: block; margin: auto;" />
]

.pull-right[

]

.left[.footnote[Images by [Amonrat Rungreangfangsai](https://www.vecteezy.com/members/amy1313)]]

Thankfully, I came across DIVIO [website](https://documentation.divio.com/) that encourages me to split my documentations into manageable categories.

Following in its footsteps, this is what I come up with

.left[.footnote[Images by [Amonrat Rungreangfangsai](https://www.vecteezy.com/members/amy1313)]]

.pull-left[

Tutorial: Github README

<img src="images/documentation-readme.jpg" width="100%" style="display: block; margin: auto;" />
]

.pull-right[

How To Guide: Cheatsheet

]

.pull-left[

Explaination: User Documentation

<img src="images/documentation-user-documentation.jpg" width="100%" style="display: block; margin: auto;" />
]

.pull-right[

Reference: Developer Documentation

]

## Take Home Advice:<br>Create a software that gives a lasting impact.

.pull-left[
<img src="images/help-people.jpg" width="100%" style="display: block; margin: auto;" />
]

.pull-right[
- The main purpose for creating a software is not to make us popular, it is to **help others with their problems**.

- A problem no matter how small can be as annoying as big ones

- The more annoying the problem the software tries to solve, the more useful it is.
]

.left[.footnote[Images by [Amonrat Rungreangfangsai](https://www.vecteezy.com/members/amy1313)]]

## Take Home Advice:<br>Create a software that gives a lasting impact.

.pull-left[
<img src="images/help-people-2.jpg" width="100%" style="display: block; margin: auto;" />
]

.pull-right[
- Don't feel discouraged when you are tasked to create a tool that does small and simple things.

- Instead "do (these) small things with great love." -- *Saint Teresa of Calcutta*

- "If you can impact a few people deeply, they will just shout from the rooftops for you. The breadth of the impact will be a matter of time". -- *Yihui Xie* [blog](https://yihui.org/en/2018/08/influence-depth-or-breadth/)

]

.left[.footnote[Images by [Amonrat Rungreangfangsai](https://www.vecteezy.com/members/amy1313)]]

## All the best...

.pull-left[

Review of advice
- Convert scripts to a web service or executable software.
- Give a software overview using cheat sheets.
- Provide helpful messages when users make a mistake.
- Include necessary software reports to show reliability.
- Organise your documentation into specific structures.

Take home advice
- Create a software that gives a lasting impact.
]

.pull-right[
<img src="images/that-is-all.jpg" width="100%" style="display: block; margin: auto;" />
]

.left[.footnote[
Images by [Amonrat Rungreangfangsai](https://www.vecteezy.com/members/amy1313)

]
]