Dario Trinchero

Dario Trinchero

PhD candidate in mathematical physics, working on topological quantum field theory

How I designed my research journal

9 minute read

Published:

Some sage advice I was given when starting my PhD was to keep a research journal. No doubt this is common practice, but to be clear, this is to be a place for recording daily work, tracking progress, outstanding tasks, lingering questions, answers to those questions, and so on. Here’s how I designed my ideal journal.

Download: GitHub repo

Requirements

After some brainstorming, I devised the following desiderata for such a journal, ranked by importance:

  1. Low activation energy: It should require almost no effort to add entries.
  2. Cross-referencing: Wherever they make sense, hyperlinks should be inserted (preferably automatically, given #1): questions should link their corresponding answers & vice-versa, there should be hyperlinked bookmarks, table-of-contents, reference lists, etc.
  3. Issue tracking: Unresolved issues (questions & TODOs) should be collected into a single (hyperlinked) list, and automatically removed upon being resolved.
  4. Progress tracking: There should be high-level progress indicators & goal trackers (eg. calendar & Gantt chart), as well as records of completed low-level tasks (eg. reading & exercises).
  5. Readability: Layout should be compact, color-coded, & readable.

Format

Given the above requirements, the first obvious design choice is the digital format of the journal. We have a couple of options here.

The simplest and most robust technology would be to write journal entries in some lightly marked up text format like Markdown. If we want to support things like color, we can process the Markdown files into HTML automatically with a tool like Kramdown. This approach has the following pros and cons:

Pros of Markdown + Kramdown
Easy hyperlinking.
Minimal boilerplate, so probably lowest possible effort to add entries.
Support for color & other formatting with CSS.
Cons of Markdown + Kramdown
Cross-referencing will be manual unless we write custom postprocessing scripts to do it.
The table-of-contents, calendar, Gantt chart, and issue tracker will each probably take a fair bit of code to implement well.
We need to design a theme from scratch - default HTML is hideous.
Extra libraries are needed to support MathJax / TeX syntax, responsive layout, etc.
Referencing citations will require extra libraries / custom code.
It is hard for collaborators to print and/or annotate entries.


Of course, we could also write directly in HTML format, but that merely inherits most of the cons of the above approach while losing most of the pros. The last alternative I considered was to implement my journal as a LaTeX class. This has the following pros and cons:

Pros of LaTex
Easy hyperlinking & automatic cross-referencing via labels.
Looks great by default.
Renders math by default.
Supports table-of-contents & PDF bookmarks by default.
Supports bibliographies & citations by default.
Packages exist for calendars, Gantt charts, and arbitrary lists-of-X.
Compiles to PDF which is easy & reliable (for others) to view, print, and annotate.
Cons of LaTeX
More boilerplate than Markdown.
Generally a finicky language prone to cryptic error messages.

In the end, this is the solution I opted for. I resolved to do my very best to reduce the boilerplate needed to add new entries. My strategy was to automate as much as possible within the class definition, so that a .tex file using the class would require only one or two short commands to add a journal entry.

Implementation

Going into this project, the most low-level LaTeX coding I had done was designing my own beamer theme. I had a pretty tough time doing that. Well, writing this class was orders of magnitude worse. My experience with both projects can be summarized as follows:

TeX is a joy to use, as long as you never try to customize anything.

Maybe it’s just my recent experience with learning Rust that has given my unrealistically-high expectations of compilers, but TeX truly never fails to throw the most unhelpful error messages imaginable. In the end, I largely resorted to reading existing LaTeX class implementations (such as that of AltaCV, the template I use for my cv), and trying to adapt the useful bits for my application. That and a lot of Googling.

The whole development process took me the better part of a few weeks. Luckily I managed to mostly get it done before my actual PhD work kicked in.

The fact that this process was so painful is exaclty the source of my motivation to make it publically available. I am quite proud of the system I ended up implementing, and I currently use it daily to track my PhD progress. I genuinely believe that others would benefit from using a similar system, and I hope that I might save them some headache.

Feature list

Needless to say, my template implements the above design requirements as a baseline, plus a few extras. To be specific, here is a list of some of the core functionality that I implemented in order to meet my requirements:

  • Simple syntax for new entries with automatic date headings
  • Compact hyperlinked table of contents & automatic PDF bookmarks
  • Project calendar that automatically links to entries & highlights current day
  • Automatically-updating Gantt charts for high-level timeline
  • Global list of unresolved issues, separated by high- & low priority, & sorted by date
  • Automatic hyperlinks between questions & their answers
  • Easy checklists

There are many more smaller features and quality-of-life improvements than the above; see the GitHub page for the current list.

Showcase of usage

Note that the syntax shown here is based on the current version (as of 20 October 2023). It is possible that this syntax may change in future updates. Please see the documentation on GitHub for up-to-date usage instructions.

Initial configuration

To use the class, save it in the same directory as your .tex file, then simply set your \documentclass to “journal” at the start of your preamble. There are a couple of class options you can pass to toggle some of the functionality:

\documentclass[
	raggedright, % ragged-right alignment (instead of justified)
	%widetoc, % wide table-of-contents (instead of 2-column)
]{journal}

Then, still in the preamble, set up the journal metadata with a few short custom commands:

\name{Research Journal}
\project{PhD Journalism}
\subject{The use of LaTeX typesetting for journalism} % only in PDF file metadata
\author{Alice Atwood \and Bob Benston}

That’s all of the necessary configuration, bar the (optional) Gantt charts, which we showcase below.

Gantt chart(s)

The last thing to customize is the file defining the Gantt charts, which of course have to be tailor-made for your particular project needs. By default, this file lives at the path /figures/gantt.tex.

Here’s the example Gantt chart definition from the template:

\begin{gantt}[Overview]{2022-11}{2025-12} % optional argument creates subsection heading
	% defining chart rows
	\phase{lit review}{2022-12}{2023-12}\\ % \\ moves to the next row in the chart
	\task{topic 1}{2022-12}{2023-03}
	\phase{research}{2024-01}{2025-01}\\
	\task[topic2]{topic 2}{2023-02}{2023-04}
	\task[research1]{research goal 1}{2024-01}{2024-07}\\
	\task*[research2]{research goal 2}{2024-07}{2025-01}
	\task[topic3]{topic 3}{2023-03}{2023-07}\\
	\task*{topic 4}{2023-06}{2023-09}\\
	\task*[topic4]{topic 4}{2023-08}{2023-12}
	\phase{writing}{2024-09}{2025-10}\\
	\milestone{reading}{2023-12}
	\task[paper1]{paper 1}{2024-09}{2024-12}\\
	\task*[paper2]{paper 2}{2025-02}{2025-04}\\
	\task*[thesis]{thesis}{2025-04}{2025-10}
	\milestone{1st paper}{2024-12}\\
	\milestone{2nd paper}{2025-04}
	\milestone{PhD}{2025-10}

	% additional links
	\link{topic2}{topic3}
	\link[link type=f-s]{topic4}{research1}
	\link[link type=rdldr*, link bulge 2=2.5, link mid=1/8]{research1}{paper1}
	\link[link type=rdldr*, link bulge 2=5.5, link mid=1/8]{research2}{paper2}
\end{gantt}

This is a little chunkier, but you only need to design such a chart once or twice for your entire project duration. Moreover, we are using a bunch of shortened commands (\phase, \task, etc) defined by the class to simplify the syntax here. Otherwise, this syntax is thoroughly documented in pgfgantt documentation.

See the second screenshot below for the lovely chart produced by the above definition.

Front-matter

With the configuration out of the way, you can automatically generate a whole bunch of automatically-updating front-matter in a few lines:

\begin{document}
\maketitle
\tableofcontents % optional table of contents
\calendar[11-01]{2022}{2025} % optional calendar
\timelines % optional Gantt charts
\listofissues % optional list of unresolved questions & TODOs

Journal entries

Finally, the part that matters for daily usage. Adding a new journal entry is as simple as:

\logday
Your entry here.

We support a bunch of custom environments like checklists and task lists. The latter can record todos, questions, and answers, as well as completed reading and exercises. For all of these tasks, the “Open Issues” lists are automatically kept up-to-date and hyperlinked.

Here is a demo of the syntax for the functionality we describe above. It has slightly more boilerplate than the mere plain entry, but such is the nature of LaTeX - we cannot entirely avoid nonsense like \begin{...} and \end{...}.

\logday
Here is a checklist:
\begin{checklist}
	\item* Checked item
	\item! Crossed item
	\item Unchecked item
\end{checklist}
and here is a tasklist:
\begin{tasklist}
	\todo* "Learn how to use tasklists."
	\todo? "Tick this item off."
	\read*[baez1994gauge][pp.~10--26] "You can refer to citations."
	\ex[baez1994gauge][\#~1--3] "Exercises work just like reading tasks."
	\qstn[baez1994gauge] "Why did I use this book as an example?" \label{qstn:why}
		It just makes no sense.
	\ans[qstn:why] I probably just copied a piece of my actual reference list.
\end{tasklist}

Screenshots

Let us end by showing off the pretty colors and lovely typesetting. Here are some representative screenshots:

Using my template

If you like my design, please feel free to download and use the template! You are welcome to modify / adapt it however you like to suit your needs. Feedback and/or pull requests are also strongly encouraged!