Writing a paper with github

20. June 2013. Tagged github, studies, organization, git, latex.

Yes, I am writing my bachelor thesis with github. Why do I do that? Because it supplies me with all the tools I need to make progress!

This might not work for everyone and every usecase, but I think if you mind some general rules and tips, github can really help you writing your paper (this should work for a bachelor or master thesis, a paper or even a book, too). And this does not only apply to IT or CS topics, I am studying BA and it still works.

So here it goes:

#### 1. You will need to stop using word (or anything like it). I never actually understood, why people like to write long and complicated documents with word. It crashes often, looks terrible and doesn’t really structure your document, you just make it look like it is structured.

But that is not the real problem when you want to write your thesis with github (and git obviously). The real problem is that it produces a zipfile, consisting of a bunch of weird xml files, that are difficult to understand. Thus you can’t really track changes and measure progress. Git is not made for tracking word documents, but for source files.

So what do you do instead?

Well, there are multiple possibilities. You could just use something like markdown to write your paper. But this will probably not suffice for long, if you want a proper layout on paper, maybe a bibliography and stuff like that. This is way I would recommend you to go for LaTeX.

It is not WYSIWYG (What You See Is What You Get) but WYSIWYM (What You See Is What You Mean). It has source files that can be tracked with git very well and compiled into a pdf file (or a variety of other formats) anytime.

Furthermore it really structures your document and enables you to split up different parts of the text (like chapters) into different files. Images and other assets can be stored separately which makes everything a lot nicer, too.

2. Track changes correctly and write meaningful commit messages

As we are on tracking stuff already. It might seem annoying in the beginning an when you actually write a commit message, but you will be really thankful later, when you ask yourself “Why the ** did I do that?” You can just run a simple git blame and check out why you did it.

It also really helps you to see the progress and what you have been working on over time. Think of it as a diary.

3. Use the wiki to structure your thoughts first

I started off with just taking notes on plain pieces of paper while the regular meetings and in the interviews I took. I prepared myself for meetings exactly the same way. In the beginning this worked pretty well, but over time I completely lost track of what I noted where and why and what I meant with it.

The GitHub wiki solved this problem for me. After every meeting I write down my thoughts, what I learned/got to know useful at that today. I have an index of important persons with a short description for example. I also note down concpets that I want to consider and stuff like that.

With the [[<Link Text>|<Page Name>]] shortcut, that works in markdown, too, although it is not strictly speaking a markdown feature, I can link info together that might be related but is on different pages.

I leave it to you how you structure your wiki, I personally only have very few pages with some subheadings. But as I am on a practical project I have a page with information about practice and one about theory, so I don’t completely mess everything up.

4. Use issues to keep track of todos, questions and ideas (and progress!)

Another perfect match. Whenever I have a question to ask, something to look up or an idea comes to my mind I just add it to my issues.This way I can’t forget anything.

I label it properly (I have question, idea, todo and a few for urgency) and you will never forgot what it was about. When you wanna write something you just check todos and ideas, when you are going into the meeting you just check questions. It’s that easy.

But I also use milestones. I have some pretty obvious one like turn in the paper, but I have some project-specific ones like finish off for holiday or roll out practical part, too. This way you can assign issues to your milestones and see how you are making progress. It will also show you your deadlines, so you don’t lose track.

5. Keep backups offline

Ever tried to work offline and were angry, because you had something in the cloud but could not access it right now? Well, let’s deal with that.

For your text it is pretty easy, as you have that as a git repository anyways. But you can also get the git repository of your wiki, and work with it offline. You can than use your favorite editor, or get a local webinterface (the app is called gollum). Check out your git access-tab on your repository’s wiki for more info.

Issues unfortunately are not that handy. You won’t be able to edit them while you are offline and push the changes later on (as they are not git), but you can easily get a copy of them via the API so you can at least look at them. There is a number of scripts out there already (i.e. this).

Conclusion

As you can see GitHub can be your perfect paper assistant! The best thing is: when you are finished you have a perfect history of how your project started. You can recover any state and find stuff you did in the middle. That’s what I am gonna do, when I am finished: Look back to see how and what I did in the middle. :)

Unfortunately I am unable to share my thesis repository with you, as I am not allowed to share the contents with everybody. :(

But if you implement my method for your thesis and make it a public repository I will happily link it below! :)