This site talks about my choices in terms of composing documents.

It really is more dedicated to paper structuring and collaboration, instead of lower-level writing recommendations. It isn’t supposed to be a standard that is golden in whatever way, and I also do not claim that my choices would be the right method to do just about anything. That is mainly designed for my students – particularly, in order to prevent being forced to duplicate myself each time we take effect by having a student that is newinfluenced by Claire Le Goues’ post some time straight back). Nonetheless, if you learn this information of good use, or desire to use a comparable setup, please just do it! I am going to update this when I think about more points (or possibly find strong reasons why you should do things an additional method in the future).

Setup & Directory Construction

For each and every new paper we work with, please produce a personal GitHub repository under our GitHub company with all the following name paper- – . As an example, if I happened to be the primary writer of the paper and intending to submit the job to ICSE ‘18, i might name it paper-nadi-icse18 . Assume we began working on a paper, but nonetheless don’t have actually a tangible location in brain. If that’s the buy essay online us case, utilize some descriptive expression. For instance, if we had been focusing on extracting configuration constraints, the repo title is paper-nadi-config-constr . Credits: we discovered this naming strategy inside my time at TU Darmstadt and discovered it quite helpful, since typically team’s GitHub company might 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 utilizing LaTeX. In the event that you don’t now know LaTeX may be the time for you to discover.

Whenever we are targetting a particular conference, be sure to obtain the right template for the seminar. it will be this kind of shame getting a desk reject, as a result of with the incorrect template! Whenever we aren’t certain which meeting we shall target, then simply utilize the standard ACM or IEEE template for the moment, but be sure to change to the best one when we choose a meeting

Rename the primary LaTeX file as main.tex and ensure that is stays within the directory that is main. Make an independent tex apply for each area when you look at the paper, and organize the directory as follows (this instance assumes we have been utilising the ACM template):

The >main.tex file as required. This can be could be a good example of just exactly what main.tex seems like:

  • Please usually do not include any generated files in the git repository ( 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 attend it 5 times before pushing it to the repo till you have finished the whole section and revised. I am going to maybe maybe not read it 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 a pdf up and deliver it to you personally or we’d stay together and undergo a printed section where I’ll mark up things even as we get. In either situation, We anticipate that you’ll upgrade things into the repository a short while later. In phases, after the content is just a bit stable, i shall typically begin things that are editing the repository. this may frequently be through making remarks within the text. Making it easier in my situation to go out of commentary as well as you to definitely react to them if required, will have the following macros defined (clearly, alter colors as required). Then remove it from the text if a comment has already been addressed and resolved.

  • There could be some elements of the paper still under construction, e.g., figures you nevertheless still need to have or perhaps a citation you nevertheless still need to locate. Of these, have actually a TODO macro defined such we can simply spot what’s left doing:
  • To be sure we could plainly see figures that want become dual checked, surround all figures with the next \checkNum macro. Remember to remove the color through the macro before submitting. Credits: once again, this is certainly another trick we discovered from TU Darmstadt pupils.

If you are the only person focusing on the repository, there are not any 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 could try this via Slack or e-mail.

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

While We have perhaps not strictly implemented this myself thus far, i believe it really is smart to possess each phrase in a different line (Sebastian Proksch at TU Darmstadt, now at U. Zьrich utilized to follow along with this). This makes it much easier to versions that are diff 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 We have a few pet peeves:
    • make certain you understand when you should utilize the vs. a vs. neither. If you learn me personally constantly incorporating or getting rid of the ’s from your own text and also you don’t know very well what the problem is, come ask me personally why. Please don’t simply keep doing the ditto over and once more; it is frustrating for both of us.
    • When you yourself have a phrase that’s four lines very long, chances are confusing and hard to know. Break it down. The greater amount of concisely you are able to say one thing the higher. If you want more words, utilize numerous sentences. You will need to make the audience through the movement of the arguments. Don’t readers that are loose forcing them to return and read each sentence or paragraph twice. Make their life easier. Reviewers happen to be particular them another reason to shoot your paper down as it is.. don’t give.
    • To prevent typing a list that is long and it’s hard to remember them all now), Claire Le Goues’ post has good tips about composing design. Nevertheless, note just how she prefers obtaining the entire paper in one file and I also don’t ? – thus, each advisor’s preferences that are personal.
  • As a whole, prepare yourself to do iterations that are multiple the paper. become re-organzing things several times. Have patience and provide your self time that is enough of this deadline for those iterations.
  • remember my PhD advisor, Ric Holt, for the expressed words“big picture”. They’ve been now etched during my brain. What exactly do they mean? You always wish to tell the reader exactly what the big photo is. What’s the context associated with the issue you might be working with? What precisely you doing? Why should they worry about what you yourself are doing? That will benefit from the results? Just how can the total outcomes be properly used? a good paper never ever actually leaves your reader wondering about some of these points. Preferably, the introduction should currently answer a lot of these picture that is“big concerns without necessary overwhelming the reader with a great deal of low-level details or part “stories”.

    Pertaining to big photos, I’m a big fan of overview figures a numbered or labelled example of most actions regarding the methodology or the the different parts of a framework, as an example. These figures can be referenced in then the text, and also make life a great deal easier for your reader. In addition they force one to compose in a far more structured method. Examples: Figure 1, Figure 1, or Figure 1. Notice the way they are typical Figure 1 :-)

    Preferably, you wish to make your experiments such it is simple to re-run them and upgrade the outcomes into the paper as required.

    For numbers, plots etc., the simplest way to achieve this is to have script for reproducing the graph. Therefore we can essentially upgrade a label, re-run the script and then re-compile our LaTeX file. In the event that you currently do your numbers in LaTeX (We really don’t simply because We never ever attempted it maybe perhaps maybe not because We have such a thing against it), then chances are you currently guarantee they’ve been always as much as date.