Documentation Tools

In previous years, scientists kept notes and laboratory notebooks to record their data and to update their methodology and theory. In the digital age, many of these notes are informal, contained in power point slides, emails, Microsoft Word, Excel Spreadsheets, and the other.

This approach to to documentation is largely inefficient. The question is how to create an easy-to-use documentation process, which is largely autonomous?

Proprietary Formats

Proprietary format such as Word and Excel spreadsheets have real-time collaboration tools, but they are not free and are tied specifically towards a cloud platform (Google Drive for Google Docs and the equivalent for Microsoft Office). More importantly, their file format are binary and they don't work well with a text-based documentation toolchain such as utilizing git and GitHub.

Sphinx

LaTeX

This is not a software development topic, but this is probably the best place for it? I prefer to use LaTeX to make documents. But I am not here to convince you. LateX has been around for A LONG TIME, and a lot of the information on the internet is quite dated, so this is somewhat of a gentle guide.

Compiling a LaTeX document

Compiling a LaTex document is actually fairly complicated, so I'm not going to describe it. Instead I'm providing a link to latexmk[1], which is included with most Windows, Linux, and OSX distributions of LaTeX.

latexmk -pvc -f -pdf foo

For compiling using xelatex

latexmk -xelatex -pv foo

Occasionally, you will get this an error [2],

latexmk -xelatex -pv -e "$max_repeat=10" foo

References:

[1] Using Latexmk, https://mg.readthedocs.io/latexmk.html

[2] https://tex.stackexchange.com/questions/27450/how-to-make-latexmk-work-with-xelatex-and-biber

Snippets to use a lot

I'm lazy and i like to cut and paste

INSERTING FIGURES

\begin{figure}[h]

    \centering

    \includegraphics{mesh}

    \caption{a nice plot}

    \label{fig:mesh1}

\end{figure}