Writing Professional Data Science Documentation | by Adam Gajtkowski | Towards Data Science

Documentation is an important part of being a data scientist. I propose to use R Markdown and LaTeX to document data science models.
There are several desirable properties of good documentation
easily accessible
readable
consistent across projects
reproducible
Using LaTeX inside R Markdown allows users to use consistent LaTeX formatting across numerous project, write professional mathematical formulas explaining given model, consistently reference figures/articles, and dynamically produce graphs from outputs of the model.
LaTeX is a document preparation system originally intended for academics to introduce consistency across formatting of scientific publications. It can be also successfully used to document machine learning models.
In order to use it, you need to have installed LaTeX distribution. You don’t need to install the full version of LaTeX. It is possible to use the R package tinytex to render documents with LaTeX code.
tinytex::install_tinytex()
To install missing LaTeX libraries, you can install it using tinytext by pasting error message as an argument.
tinytex::parse_install()
For example you can pass log file to fix all missing libraries error.
tinytex::parse_install("filename.log")
The main use of LaTex within R Markdown is typing mathematical formulas and numbering equations, adding references. Here’s the example of code I typed for Granger Causality.
\begin{equation}\begin{pmatrix}U_{t} \\OLI_{t} \\\end{pmatrix}=\begin{pmatrix}\alpha_{1} \\\alpha_{2} \\\end{pmatrix}+\begin{bmatrix}\delta_{1,1,1} & \delta_{1,1,2} \\\delta_{1,2,1} & \delta_{1,2,2} \\\end{bmatrix}\begin{pmatrix}U_{t-1} \\OLI_{t-1} \\\end{pmatrix}+ ... +\begin{bmatrix}\delta_{p,1,1} & \delta_{p,1,2} \\\delta_{p,2,1} & \delta_{p,2,2} \\\end{bmatrix}\begin{pmatrix}U_{t-p} \\OLI_{t-p} \\\end{pmatrix}+\begin{pmatrix}\eta_{1t} \\\eta_{2t} \\\end{pmatrix}\end{equation}
And that’s how it looked in the rendered document.
I realise that the above code may look scary. LaTeX can have a steep learning curve, however once you type several first equations with google’s help, it becomes significantly easier and more automatic.
R Markdown allows you to divide documents into sections/subsections, add title, add table of contents, and produce graphs which could document outputs of a given model. You can write R/Python code inside code chunks, and LaTeX formulas and text between the chunks. R Markdown document is easy to edit and render. To get more information about R Markdown, setting parameters and rendering HTML/PDFs I recommend using R Markdown Cookbook https://bookdown.org/yihui/rmarkdown-cookbook/rmarkdown-process.html
Powering up agile R Markdown documentation with consistency and possibilities of LaTeX gives you a powerful tool to document data science models, which is crucial for future data scientists who will be working on your projects, as well as more technical stakeholders who may want to know more details about your work.
I recommend including the R Markdown document together with rendered HTML/PDF inside your project git repository, inside the documentation folder. This will allow you to easily access more technical details of the model, and make any necessary corrections. Also, you can only use LaTeX when you render PDFs. Otherwise feel free to use HTML.
List of useful resources for LaTeX and R Markdown