It is more dedicated to paper structuring and collaboration, in the place of lower-level writing recommendations. It’s not supposed to be a standard that is golden in any manner, and I also usually do not declare that my choices will be the right method to do just about anything. This is certainly mainly intended for my students – particularly, to prevent being forced to duplicate myself each time I begin working having a brand new student (encouraged by Claire Le Goues’ post some time straight back). Nevertheless, 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 of more points (or even find strong reasons to do things in another method later on).
Setup & Directory Construction
For each new paper we work with, please produce an exclusive wikipedia reference GitHub repository under our GitHub company because of the after name paper- – . For instance, 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 began taking care of a paper, but nevertheless don’t a tangible place in mind. In that case, make use of some phrase that is descriptive. For instance, if we had been taking care of extracting configuration constraints, the repo title could be paper-nadi-config-constr . Credits: we discovered this naming strategy inside my time at TU Darmstadt and discovered it quite of good use, since typically a combined team’s GitHub company might have a variety of paper repos, rule repos, grant repos etc. Having some fixed prefix for documents made them simpler to spot.
We will compose all documents utilizing LaTeX. In the event that you don’t know LaTeX, now may be the time for you to discover.
When we are targetting a certain conference, be sure to obtain the right template for the seminar. It will be this kind of shame to obtain a desk reject, as a result of making use of the template that is wrong! Then just use the standard ACM or IEEE template for the time being, but make sure to switch to the right one when we decide on a conference if we are not sure which conference we will target
Rename the primary LaTeX file as main.tex and keep it within the main directory. Make a split tex apply for each area within the paper, and organize the directory as follows (this instance assumes our company is utilising the ACM template):
The >main.tex file as required. This can be is a good example of what main.tex seems like:
- Please usually do not include any generated files in the git repository ( ag e.g., .blg, .log, .aux etc.). And also this includes the main.pdf file.
We’re going to collaborate through the git repository. Therefore please please please commit regularly and push the repo. You don’t have actually to wait patiently till you’ve got completed your whole area and revised it 5 times before pressing it to your repo. i am going to not see clearly anyways until such time you let me know it really is ready so commit often therefore we have actually good history in the event one thing goes incorrect so we don’t loose all your valuable writing should your computer crashes.
For early drafts, i might typically mark a pdf up and deliver it for your requirements or we might sit together and undergo a printed part where I’ll mark up things even as we get. In either situation, We expect that you’ll upgrade things into the repository a short while later. In phases, when the content is really a bit stable, i shall typically begin modifying things in the repository. This can often be through making reviews when you look at the text. Making it easier for me personally to go out of remarks as well as you to definitely react to them if necessary, also have the following macros defined (obviously, alter colors as needed). In case a remark was already addressed and solved, then eliminate it through the text.
- There might be some right elements of the paper nevertheless under construction, e.g., figures you nevertheless still need to have or a citation you nonetheless still need to get. For those, have actually a TODO macro defined such that people can quickly spot what’s left to accomplish:
- To be sure we could obviously see figures that want become dual checked, surround all figures with the\checkNum macro that is following. Remember to eliminate the color through the macro before submitting. Credits: once more, that is another trick we discovered from TU Darmstadt pupils.
when you’re the only one focusing on the repository, there are not any odds of conflicts. But, when we are both modifying the paper, we must coordinate in a way that our company is perhaps not both modifying the exact same parts (that’s why i love each part to get in a different file). We could try this via Slack or e-mail.
Before you decide to try pulling modifications to your repository that is local yes to commit your present changes first and then do git pull –rebase . Perform some same before pressing changes. This decreases the probability of us getting unneeded conflict that is merge and offers a cleaner history for all of us (i.e., no unneeded merges).
Myself so far, I think it is a good idea to have each sentence in a separate line (Sebastian Proksch at TU Darmstadt, now at U. Zьrich used to follow this) while I have not strictly implemented this. This will make it better to versions that are diff resolve conflicts. We shall you will need to implement this myself in the years ahead.
- I don’t claim to be the world’s writer that is best, but We have several pet peeves:
- make certain you understand when you should utilize 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 thing that is same and once more; it is frustrating for both of us.
- It is likely confusing and hard to understand if you have a sentence that’s four lines long. Break it down. The greater amount of concisely you can easily say one thing the higher. If you want more terms, utilize numerous sentences. You’ll want to just take the audience through the movement of one’s arguments. Don’t loose visitors by forcing them to return and read each sentence or paragraph twice. Make their life easier. Reviewers already are particular because it is.. don’t provide them with another explanation to shoot your paper straight down.
- In order to avoid typing an extended list (plus it’s hard to remember them all now), Claire Le Goues’ post has good recommendations on composing design. Nonetheless, note just how she prefers obtaining the whole paper in one file and I also don’t ? – thus, each advisor’s individual choices.
- as a whole, expect you’ll do iterations that are multiple the paper. find yourself re-organzing things times that are several. Have patience your self sufficient time ahead regarding the deadline for these iterations.
I usually keep in mind my PhD advisor, Ric Holt, for the expressed words“big picture”. These are generally now etched in my own mind. do they suggest? You constantly desire to inform your reader just what the big image is. What’s the context associated with the nagging problem you might be coping with? Exactly what are you doing? Why should they value what you are really doing? Who can gain from the outcomes? How do the outcomes ? a paper that is good renders 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 lot of low-level details or part “stories”.
Linked to big images, I’m a big fan of overview numbers that offer a numbered or labelled example actions regarding the methodology or even the the different parts of a framework, for instance. These figures can be referenced in then the text, and then make life a great deal easier for your reader. In addition they force one to compose in an even more structured means. Examples: Figure 1, Figure 1, or Figure 1. Notice how they are typical Figure 1 🙂
Ideally, make your experiments such them and update the results in the paper as needed that it is easy to re-run.
For figures, plots etc., the way that is best to get this done would be to have a script for reproducing the graph. So we can fundamentally upgrade a label, re-run the script and then re-compile our LaTeX 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.