These pages talks about my preferences with regards to composing documents.

It really is more dedicated to paper structuring and collaboration, instead of writing that is lower-level. It’s not supposed to be a golden standard in in whatever way, and I also usually do not declare that my choices would be the right method to do just about anything. This might be mainly designed for my students – particularly, to prevent being forced to duplicate myself each and every time I take effect with a brand new pupil (motivated by Claire Le Goues’ post a little while straight right back). Nonetheless, if you discover this information helpful, or desire to use a setup that is similar please proceed! I shall upgrade this when I think of more points (or even find reasons that are strong do things an additional method in the future).

Setup & Directory Structure

For each new paper we work with, please produce an exclusive GitHub repository under the following name paper to our GitHub organization- – . As an example, I would name it paper-nadi-icse18 if I was the main author of the paper and planning to submit the work to ICSE ‘18 . Assume we started focusing on a paper, but nonetheless don’t a tangible place in head. In that case, utilize some descriptive phrase. The repo name would be paper-nadi-config-constr for example, if we were working on extracting configuration constraints . Credits: we learned this naming strategy inside my time at TU Darmstadt and discovered it quite of good use, since typically a combined team’s GitHub organization will have a mixture of paper repos, rule repos, grant repos etc. Having some fixed prefix for documents made them better to spot.

We shall compose all documents making use of LaTeX. In the event that you don’t now know LaTeX could be the time for you to learn.

Whenever we are targetting a conference that is specific be sure to have the right template for the meeting. It will be this kind of shame to obtain a desk reject, due to utilising the template that is wrong! Whenever we are not yes which seminar we are going to target, then simply utilize the standard ACM or IEEE template for the moment, but be sure to change to the correct one once we choose a meeting

Rename the LaTeX that is main file main.tex and ensure that it stays into the directory that is main. Make a split tex apply for each area when you look at the paper, and organize the directory as follows (this instance assumes our company is utilizing the ACM template):

The >main.tex file as required. That is is a good example of exactly just what main.tex seems like:

  • Please try not to include any generated files in the git repository ( e.g., .blg, .log, .aux etc.). And also this includes the main.pdf file.

Collaboration

We are going to collaborate through the repository that is git. Therefore please please please commit regularly and push the repo. You don’t have actually to hold back it 5 times before pushing it to the repo till you have finished the whole section and revised. I am going to not see clearly anyways me it is ready so commit often so we have good history in case something goes wrong and so we don’t loose all your writing in case your computer crashes until you tell.

For very very early drafts, I would personally typically mark up a pdf and deliver it to you personally or we might stay together and proceed through a printed part where I’ll mark up things once we go. Either in situation, We anticipate you will upgrade things when you look at the repository a while later. In phases, after the content is just a bit stable, i shall typically begin things that are editing the repository. This will often be through leaving feedback when you look at the text. To really make it easier if necessary, always have the following macros defined (obviously, change colors as needed) for me to leave comments and for you to respond to them. Then remove it from the text if a comment has already been addressed and resolved.

  • There might be some areas of the paper nevertheless under construction, e.g., figures you nonetheless still need getting or perhaps a citation you nevertheless still need to get. of these, a TODO macro defined such that we can certainly spot what’s left doing:
  • To ensure we could obviously see figures that want become dual checked, surround all figures with the\checkNum macro that is following. Be sure to eliminate the color through the macro before publishing. Credits: once more, that is another trick we discovered from TU Darmstadt pupils.

If you’re alone focusing on the repository, there are no odds of disputes. Nonetheless, that we are not both editing the same sections (that’s why I like each section to go in a separate file) if we are both editing the paper, we should coordinate such. We are able to repeat this via Slack or e-mail.

Before you take to pulling changes to your repository that is local sure to commit your changes first after which do git pull –rebase . Perform some same before pressing changes. This decreases the probability of us getting unneeded merge conflict messages and offers a cleaner history for people (in other words., no unneeded merges).

While i’ve maybe not strictly implemented this myself to date, i believe it really is a good notion to possess each sentence in an independent line (Sebastian Proksch at TU Darmstadt, now at U. Zьrich utilized to check out this). This will make it better to diff variations and resolve conflicts. We shall attempt to implement this myself in the years ahead.

  • We don’t claim to end up being the world’s best journalist, but I have a few pet peeves:
    • be sure you understand when to make use of the vs. a vs. neither. Me constantly adding or removing the ’s from your text and you don’t understand what the problem is, come ask me why if you find. Please don’t simply keep doing the same task over and once more; it is frustrating for both of us.
    • For those who have a sentence that’s four lines very long, chances are confusing and hard to know. Break it down. The greater concisely you are able to say one thing the higher. If you want more terms, utilize numerous sentences. You will need to just take the reader through the movement of the arguments. Don’t loose visitors by forcing them to return and read each sentence or paragraph twice. Make their life easier. Reviewers are actually particular them another reason to shoot your paper down as it is.. don’t give.
    • In order to prevent typing an extended list ( and it’s difficult to remember them all now), Claire Le Goues’ post has good recommendations on composing design. However, note exactly how she prefers having the paper that is whole one file don’t ? – thus, each advisor’s preferences that are personal.
  • As a whole, prepare yourself to do iterations that are multiple the paper. We may find yourself re-organzing things many times. have patience and provide your self time that is enough associated with due date for those iterations.
  • keep in mind my PhD consultant, Ric Holt, for the expressed words“big picture”. These are generally now etched in my mind. Just what exactly do they suggest? You constantly would you like to tell your reader just what the picture that is big. What’s the context of this issue you will be working with? Exactly what are you doing? Why should they worry about ? That will gain out from the outcomes? just exactly how can the total outcomes ? a good paper never ever makes your reader wondering about some of these points. Preferably, the introduction should already respond to many of these picture that is“big concerns without necessary overwhelming your reader with a great deal of low-level details or part “stories”.

    Pertaining to big images, I’m a big fan of overview numbers a numbered or labelled example of all of the actions associated with the methodology or even the the different parts of a framework, as an example. These figures can then be referenced in the text, and then make life a great deal easier for your reader. In addition they force one to compose in an even more way that is structured. Examples: Figure 1, Figure 1, or Figure 1. Notice the way they are typical Figure 1 🙂

    Preferably, you need to make your experiments such that it’s an easy task to re-run them and upgrade the outcome in the paper as required.

    For numbers, buy essays online plots etc., the way that is best to get this done would be to have script for reproducing the graph. Therefore we can fundamentally upgrade a label, re-run the script and re-compile our LaTeX then file. Then you already guarantee they are always up to date if you already do your figures in LaTeX (I personally don’t just because I never tried it not because I have anything against it.