These pages covers my choices with regards to papers that are writing.

It really is more dedicated to paper structuring and collaboration, instead of writing that is lower-level. It’s not supposed to be a standard that is golden in whatever way, and I also usually do not declare that my choices would be the right method to do just about anything. This really is mainly designed for my students – particularly, in order to prevent having to duplicate myself each and every time I begin working having a student that is newinfluenced by Claire Le Goues’ post a little while straight right back). But, if you discover this information helpful, or desire to use a setup that is similar please just do it! I am going to upgrade this when I think about more points (or possibly find reasons that are strong do things an additional method later on).

Setup & Directory Construction

For virtually any brand new paper we work with, please produce an exclusive GitHub repository under the following name paper to our GitHub organization- – . For instance, if I happened to be the key composer of the paper and about to submit the task to ICSE ‘18, i might name it paper-nadi-icse18 . Assume we began taking care of a paper, but nonetheless don’t have actually a venue that is concrete brain. In that case, make use of some descriptive expression. 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 within my time at TU Darmstadt and discovered it quite of good use, since typically a combined group’s GitHub company will have a variety of paper repos, rule repos, grant repos etc. Having some fixed prefix for papers made them simpler to spot.

We shall compose all documents making use of LaTeX. In the event that you don’t understand LaTeX, now could be the time to discover.

Whenever we are targetting a particular conference, remember to have the right template for the seminar. It might be this kind of shame getting a desk reject, due to utilising the incorrect template! When we aren’t certain which seminar we are going to target, then simply use the standard ACM or IEEE template for the time being, but remember to change to the correct one once we determine a seminar

Rename the LaTeX that is main file main.tex and ensure that it stays within the directory that is main. Make a separate tex apply for each part within the paper, and organize the directory as follows (this instance assumes our company is utilizing the ACM template):

The >main.tex file as required. It is is a good example of exactly what main.tex appears like:

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

Collaboration

We shall collaborate through the repository that is git. Therefore please please please commit regularly and push the repo. You don’t have actually to wait patiently it 5 times before pushing it to the repo till you have finished the whole section and revised. I’ll perhaps not see clearly anyways until such time you let me know it’s ready so commit often so we have actually good history just in case one thing goes incorrect so we don’t loose your entire writing should your computer crashes.

For very very early drafts, I would personally typically mark up a pdf and deliver it for you or we might stay together and proceed through a printed part where I’ll mark up things once we get. Either in full instance, We anticipate you will update things into the repository a short while later. In later on phases, after the content is a little stable, i am going to typically begin things that are editing the repository. This can often be through making feedback into the text. Making it easier for me personally to go out of remarks as well as for you to definitely react to them if required, will have the following macros defined (clearly, change colors as needed). Then remove it from the text if a comment has already been addressed and resolved.

  • There might be some components 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 we can simply spot what’s left doing:
  • To be sure we are able to demonstrably see figures that have to be dual checked, surround all figures with the\checkNum macro that is following. Remember to eliminate the color through the macro before publishing. Credits: once more, this might be another trick we discovered from TU Darmstadt pupils.

When you’re the only person working on the repository, there are not any odds of disputes. Nevertheless, whenever we are both modifying the paper, we ought to coordinate so that we have been perhaps not both modifying the exact same parts (that’s why I like each part to get in a different file). We are able to try this via Slack or e-mail.

Before you take to pulling changes into the repository that is local yes to commit your present changes first after which do git pull –rebase . Perform some same before pushing modifications. This decreases the likelihood of us getting unneeded conflict that is merge and offers a cleaner history for people (for example., no unneeded merges).

While We have perhaps not strictly implemented this myself to date, i do believe it really is a good clear idea to possess each phrase in a different line (Sebastian Proksch at TU Darmstadt, now at U. Zьrich utilized to check out this). This makes it more straightforward to diff variations and resolve conflicts. We shall you will need to implement this myself moving forward.

  • We don’t claim to end up being the world’s best writer, but We have a few pet peeves:
    • make certain you understand when you should utilize the vs visit the site here. a vs. neither. If you learn me personally constantly incorporating or getting rid of the ’s from your own text and you also don’t know very well what the problem is, come ask me personally why. Please don’t simply keep doing the thing that is same and once again; it is frustrating for both of us.
    • When you have a phrase that is four lines very long, chances are confusing and hard to know. Break it down. The greater concisely it is possible to say something the greater. If you need more terms, utilize multiple sentences. You will need to just take the audience 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 since it is.. don’t provide them with another explanation to shoot your paper down.
    • In order to avoid typing a list that is long and it’s difficult to remember now), Claire Le Goues’ post has good recommendations on composing design. Nonetheless, note just how she prefers getting the paper that is whole one file and I also don’t ? – thus, each advisor’s preferences that are personal.
  • Generally speaking, anticipate to do iterations that are multiple the paper. We possibly may find yourself re-organzing things times that are several. Have patience your self time that is enough associated with due date of these iterations.
  • I usually keep in mind my PhD consultant, Ric Holt, for the expressed words“big picture”. They have been now etched in my brain. do they suggest? You constantly like to inform the reader exactly what the picture that is big. What’s the context for the issue you may be coping with? What precisely you doing? Why should they worry about what you yourself are doing? That will gain out from the results? How can the total outcomes be properly used? a good paper never ever actually leaves the reader wondering about any of these points. Ideally, the introduction should currently respond to many of these “big picture” concerns without necessary overwhelming your reader with a great deal of low-level details or part “stories”.

    Pertaining to big photos, I’m a fan that is big of numbers that offer 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 also make life a great deal easier for your reader. They even force you to definitely compose in an even more way that is structured. Examples: Figure 1, Figure 1, or Figure 1. Notice the way they Figure 1 🙂

    Ideally, make your experiments such that it’s simple to re-run them and upgrade the outcome into the paper as required.

    For figures, plots etc., the simplest way because of this is always to have script for reproducing the graph. Therefore we can essentially upgrade a label, re-run the script and re-compile our LaTeX then file. If you currently do your numbers in LaTeX (We physically don’t simply because I never ever attempted it maybe not because We have such a thing against it), then you definitely already guarantee they have been always as much as date.

Leave a comment

Your email address will not be published. Required fields are marked *