Handling thesis drafts

If you are doing your thesis under my supervision, then you need to read this article. It describes how we interact using online tools.

Your thesis is a major project, so it needs to be managed with different rules. It is not a letter. Microsoft Word is good for a letter, but it is not the best for a thesis. The following strategy will allow us to adapt Microsoft Word or Google Docs for a major project.

My method uses text files in Markdown format, that are later handled by pandoc, a versatile tool for document preparation. These files can be managed and distributed using Git, so all versions are stored and several people can work on them at the same time, even without internet access. Nevertheless, if Markdown and Git are not tools that you use frequently, you can use Microsoft Word or, better, Google Documents. The last one is preferable, since it allows several editors at the same time, if internet access is available. Moreover, if you copy a Microsoft Word file in .docx format, Google Documents will and handle it correctly.

In the rest of this document we will assume that we use Word files. Still, most of the recommendations are valid for Markdown files.

• Make one file for each chapter. Filenames can include a number to indicate the order. For example:

   00-front-matter.docx
   01-introduction.docx
   02-methods.docx
   03-results.docx
   04-discussion.docx

• The first line of each chapter is the title. Mark it as a Header 1 using the styles tool. Do not include the word “Chapter”. That will be added by the system. Write the first letter in uppercase and the rest in lowercase letters, as you would write any regular phrase.

• Mark each section as Header 2, using lower case letters as any phrase. You can also mark subsections as Header 3, but it is better to avoid Header 4 and further.

• Forget about colors and fonts. All these details will be solved at the very end of the writing and editing process. The only exception is the usage of italics for scientific names of organisms and gene names.

  Most of the times when people use bold, they really mean “title” or other structural element.

• Figures and tables are complicated. Ideally we should handle them in separate files. Most journals use that format. In many cases the figures and tables are results of the execution of a program. We need to keep that program so we can reproduce the figure or table if necessary. If you created the table manually, keep the spreadsheet.

  If necessary you can include figures and tables in your draft, as a reference. But the best-quality image and table should be kept in an independent file.

• Figures and tables have captions, but they are not easy to manage in Google Documents. A partial solution is to write the caption immediately after the figure/table. For the process we will use, the first word in the figure caption should be #fig:X, where X is any text that identifies the figure, such as a number or a keyword.

  The same idea is valid for tables, but using #tab:X instead.

• To reference the figure/table, we use @fig:X and @tab:X. For example we can say

  The main result can be seen in @fig:results.

  [image here]
  #fig:results Main results of this paper. We observe that…

  The system will handle the numbers in the correct way, and include the word Figure or Table in each case.

• We take a similar approach to handle the bibliographic references. Each reference has an id, often like Author2021. We manage the references in a text file called references.bib written in BiBTeX format. Practically all journals, databases, and even Google Books, can provide the citation data in BiBTeX format. Moreover, it is easy to get it if we know the DOI of the article.

  If we do not yet have a references.bib file, we can start creating a Google Sheet with the bibliographic information. The only necessary columns are the reference id (Author2021) and the DOI. If the document has no DOI, then we need to add columns like title, authors, journal, date, and so on. The same rule applies for books and chapters.

  If the material referenced is a web page, we also need a title, an URL, and the date when the page was visited. This last part is important since the webpages may change with time.

• To cite a paper in our document, we write [@Author2021]. At the last moment we will decide the citation style, and we may change it depending on the journal where the paper is submitted. The system will handle all of that for us.

• Footnotes are easy. Just use the regular footnotes of Google Docs.

This is the protocol as 2021-12-12 00:00:00 +0300. It may change later as we use it. Please ask any question that arises.