Which tool to write a PhD thesis/manuscript: quarto Book or quarto Manuscript? Pro&cons based on your experience

[KleinWurm]

Description

Good morning Quarto community!

I would like to open a discussion about the use of Quarto to write a PhD thesis/manuscript. If it has already been answered please point me to the right direction because I was not able to find guidance elsewhere. I am very new to this exercice so please, do not hesitate to share your feedback and experience on the things that are very much needed when writing a PhD thesis, I might have overlooked at least some of them.

Quarto makes it possible to write plain text, possibly complex, documents without overcrowding the writing with divs and spans. It is possible to use templates (css, others?) to customize the appearence, it supports cross-referencing, caching, etc. Thus it holds the promise to be good tool for writing long and complex documents such as a PhD manuscript.

From what I have seen, a PhD manuscripts require the following:

1. a robust tool that can handle possibly hundreds of pages with an imposed layout (for example a LaTeX template provided by the university),
2. connection to reference management tool (Zotero) and cross-referencing
3. execute code from side-files, reason is, sometimes the code can be very long and it seems better to keep it on a separated file to enhance the readability of the main text.
4. keeps the writing process simple and clean to focus on the content (Markdown here you are), and support equations

Quarto Manuscripts, Books and the extension Journal article appear as relevant candidates for this task. But the first item of the previous list makes me a bit affraid of jumping into Quarto for this project as I do not know how to twist the layout to make things appear and look like the template from the university.

Then, I am not certain about the limitations of Manuscripts, Books and Journal articles and would like to avoid discovering a breaking problem after months of redactions.

Have you already used Manuscripts or Books or Journal articles projects to write your PhD thesis? Are you using it currently maybe? Do you know useful ressources that can help future readers to make their mind? What are the pro and cons of using one of them? Which type is the most relevant in your opinion?

Have a great day,

Edit: I am aware that Extension for a PhD thesis with Quarto exists but, if I am not mistaken, it was before Manuscripts was released.

[cscheid]

A manuscript is really intended as a journal manuscript, and not for the length of a thesis. A thesis is much closer to a book, so I would use that.

But the first item of the previous list makes me a bit affraid of jumping into Quarto for this project as I do not know how to twist the layout to make things appear and look like the template from the university.

That's a very good worry to have. I'm the main Quarto dev now but I was a tenured academic professor in a US university before joining the project. So, if you allow me to put my professor hat back on for three minutes: your job to write a thesis will be hard enough as it is. If you're not already familiar with templates, etc, I would use whatever tool your current colleagues are using, and focus on the thesis itself rather than the tech around it!

[KleinWurm]

First, many thanks @cscheid and @baptiste for your insights!

I understand that if I choose to write the thesis using Quarto, I should use a Book project. My main supervisor is open to use Markdown editing for this project and we already faced the limit of MS Word in terms of stability when it comes to big documents in a previous work.

It is very good to know that worrying about the time-consumming aspect of templating and you are very right to say that the job is to write a thesis and not showcase a writing tech (even though it is addictive to learn them).

I will give Quarto Book a try and add feeback in this discussion as soon as possible.

[sarahwarchhold]

Hi @KleinWurm, how's it going for you? I'm also writing my dissertation with quarto books and was wondering if you have some insights how it's going for you or if you faced any issues in the meantime. Do you use separate files for the main analysis code?
Best and good look!

[arnaudgallou]

@sarahwarchhold You might find my answer below useful.

[KleinWurm]

Hi @sarahwarchhold thanks for your interest. I am still in the redaction process for an article. Here are some personnal feedback about it around the main reasons I chose Quarto in the first place.
To answer quickly to your question, yes I use separate files from the main analysis code, I even use separate R projects! Otherwise the Quarto project was too crowded.

The possibility to use Git

One of the main reasons that pushed me towards Quarto and Markdown in general was to use Git to keep track of the versions of the document. In practice I do not use it much as the other authors do not use Git and prefer to use a Word document to suggest changes. Thus it is not possible to use the tools of GitHub or Gitlab to comment, suggest edits, etc. and doing this alone can be cumbersome if like me, you do not have much experience.

Another problem is linked to the fact that Git keeps track of change on a per-line basis. In Quarto, an entire paragraph can be one line in the markdown file. So I tried to add a line break in the source editor to better focus on the changes. The problem is that switching to the visual mode removed all these linebreaks...

The possibility to keep figures and numbers updated by generating them with code

This is a fantastic feature on paper but, as my data analysis workflow is quite long, I keept it separated from the actual editing of the document to avoid crowding the document with code. The figures are very good in the HTML output but are difficult to manage for the Word output. I feel like it could be more easier to produce multiple version of the figure from my analysis code and then use the figure in the different documents if needed.

Unexpected side-effect

I found the HTML output produced by Quarto is very nice to share and read on screen.

I hope you will find this useful and do not hesitate to share your experience.

[arnaudgallou]

The figures are very good in the HTML output but are difficult to manage for the Word output.

Don't bother with HTML or Word. You litterally only need to render your manuscript and figures as .pdf. If you use a manuscript project, Quarto will automatically create a .tex file (to send to the journal when publishing) and a folder with all your figures in .pdf format, which is the best you can get for PDF. If you need a specific figure version for online publishing, generate your figures as .svg too.

Only use MS Word or Google docs (see my other comment about trackdown) for collaborative writing, i.e. only use these tools for the text. Send a rendered PDF version of the manuscript to your collaborators so they can see the actual output with the figures. You only need to send them the rendered version twice, when you ask for feedback for the first time and when sending out the final version so they can approve it.

[arnaudgallou]

Chiming in to share my own experience since I've been using Quarto to write both my manuscripts and thesis. I used Quarto book for the thesis and Quarto manuscript for the manuscripts. Coming from the field of Biology and using R as the main language for the analyses, it's been a very good and smooth experience so far.

I don't think you should bother about templates and I doubt any university asks you to comply with a particular Latex template (the majority of PhD students I've met barely know what Latex is). IMO, it's more important to think about the overall project structure. My thesis dissertation consists of the actual thesis to introduce and summarize the main findings, and three papers/manuscripts. I structured the entire project as follows:

phd
├── thesis
├── paper-id-1
├── paper-id-2
└── paper-id-3

Except for the first paper that I used to experiment, my paper-id-* directories are standalone R projects consisting of 6 main directories:

.
├── data-raw    <- directory for the original, untransformed data
├── data        <- directory for any processed data
├── R           <- directory for helpers functions
├── manuscript  <- Quarto manuscript project
├── scripts     <- scripts for the data crunching, analyses and results
├── renv        <- for reproducibility, generated by the renv package

The trick to make it all work holds in 2 things: .Rprofile and --execute-dir ..

I use the .Rprofile to load helpers functions and main libraries. This allows me to have global access to helper functions in the entire project. You'll need to copy the .Rprofile to the Quarto project directory to make it work in Quarto. I do it automatically with the following pre-render/post-render commands:

project:
  type: manuscript
  pre-render:
    - cp -R ../.Rprofile ./
  post-render:
    - rm -rf .Rprofile

I then use code embedding to import the source code of the figures/tables directly into the .qmd files.

This is what a figure looks like in my .qmd files:

```{r}
#| label: fig-regressions
#| fig-height: 2.5
#| fig-width: 3
#| fig-cap: "This is a figure caption."

<<fig: regressions>>
```

Didn't work for me but the targets package can also be useful to organise the code, although the learning curve can be a bit steep. Then I render the manuscript using --execute-dir . to ensure the R code is executed at the R project level.

The thesis directory is as follows (I didn't include hidden files and the _freeze directory to keep it simple):

.
├── R
│   └── utils.R           <- helper functions
├── _book
│   └── thesis.pdf
├── _environment.local
├── _environment.required
├── _packages.tex         <- to store Latex dependencies
├── _papers.json          <- to store manuscripts/papers metadata
├── _quarto.yml
├── _references.bib
├── index.qmd             <- table of content, acknowledgements, paper list, etc.
├── thesis.qmd            <- actual thesis
├── papers.qmd            <- get and insert the manuscripts/papers
└── references.qmd

I use an .Rprofile to sources helper functions. Apart from some inline code chunks, the thesis is plain text only. I then fetch and insert the papers from each paper-id-* directory directly in papers.qmd using the Latex package pdfpages.

This is roughly what my papers.qmd looks like:

```{r}
#| label: papers
#| output: asis

for (i in seq_along(papers)) {
  paper <- papers[[i]]
  cat(
    make_chapter_title(i),
    include_paper(paper$id), # id is the name of a given paper project
    "",
    sep = strrep("\n", 2L)
  )
}
```

Where the different functions/objects are:

papers <- jsonlite::read_json("_papers.json")

include_paper <- function(project) {
  paths <- glue::glue(
    "../{project}/manuscript/_output/{name}/{name}.pdf",
    name = c("manuscript", "appendix")
  )
  paste0("\\includepdf[pages=-, pagecommand={}]{", paths, "}")
}

make_chapter_title <- function(index) {
  paste("# Paper", as.roman(index), "{.unnumbered}")
}

This is what the first iteration of the loop above looks like:

# Paper I {.unnumbered}

\includepdf[pages=-, pagecommand={}]{../paper-id-1/manuscript/_output/manuscript/manuscript.pdf}

\includepdf[pages=-, pagecommand={}]{../paper-id-1/manuscript/_output/appendix/appendix.pdf}

After setting up the basic structure, I only work in thesis.qmd and usually don't edit other files. The actual thesis is the length of a paper so I didn't feel the need to subdivide it into more files. To add a paper, I only need to add an entry in _papers.json with the name of the project containing the paper. In the end, the source code for the thesis is relatively short because all the analyses and chapters are externalized.

Finally, I wrote 2 R packages that can be very handy when writing a manuscript:

• plume to handle author data and generate author lists, contributions, etc.

• pakret to handle R package citations

I don't have time now but I'm hoping to write a package in the future to implements all these things and provide something close to a research framework.

[arnaudgallou]

how you managed the feedback and exchanges with the coauthors of your articles

I use trackdown and Google docs for that. It seems that trackdown is no longer maintained but it still works for me. There may be a similar package that does this with MS Word.

I use Git and GitHub for my research. Most of my research work is in private repos at the moment because it's not published yet. You can technically use Git/GitHub to get feedback on a manuscript, although that may become a real mess if you get feedback from many collaborators. The main issue is that not everyone uses GitHub and in that case you're usually the one who has to adapt to collaborators/supervisors.

[KleinWurm]

Again, many thanks! I will have a look at all the tools mentioned :-)

[fgardavaud]

I use trackdown and Google docs for that. It seems that trackdown is no longer maintained but it still works for me. There may be a similar package that does this with MS Word.

Dear @arnaudgallou
I'm currently writing my PhD thesis manuscrit, so I'm very interested about this discussion. I configure trackdown but the main challenge is that it's not working with .qmd document. How do you deal with this problem ? Did you find a solution to colaborate with MS Word users ?
Thanks for your sharing.

[arnaudgallou]

trackdown supports .qmd files since version 1.4.0. Simply update your version of trackdown if the one you use doesn't support it.

[fgardavaud]

thks for your reply. Indeed, I used CRAN version (stuck at 1.1) instead of Github version. Now it's working. Great 👍