It is more dedicated to paper structuring and collaboration, rather than lower-level writing tips. It’s not supposed to be a standard that is golden in any manner, and I also try not to declare that my choices will be the right solution to do just about anything. This will be mainly intended for my students – particularly, to prevent needing to duplicate myself each time we begin working with a student that is newencouraged by Claire Le Goues’ post a bit right back). Nevertheless, if you learn this information of good use, or desire to use a setup that is similar please proceed! I am going to upgrade this as I think about more points (or even find reasons that are strong do things an additional way later on).
Setup & Directory Structure
For almost any brand new paper we focus on, please produce a personal GitHub repository under our GitHub company because of the after name paper- – . For instance, if I became the key composer of the paper and likely to submit the job to ICSE ‘18, I would personally name it paper-nadi-icse18 . Assume we began taking care of a paper, but nevertheless don’t a concrete place in brain. If that’s the 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 discovered this naming strategy inside my time at TU Darmstadt and found it quite of good use, 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 will compose all documents utilizing LaTeX. In the event that you don’t understand LaTeX, now may be the time for you to discover.
Whenever we are targetting a certain conference, remember to have the right template when it comes to seminar. It will be this type of shame to obtain a desk reject, as a result of making use of the incorrect template! When we aren’t certain which meeting we shall target, then simply utilize the standard ACM or IEEE template for the moment, but remember to change to the right choice once we choose a seminar
Rename the primary LaTeX file as main.tex and ensure that is stays when you look at the directory that is main. Make a split 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. This really is will be a good example of just what main.tex appears like:
- Please don’t include any files that are generated the git repository ( ag e.g., .blg, .log, .aux etc.). and also this includes the main.pdf file.
We shall collaborate through the git repository. So please please please commit regularly and push the repo. You don’t to attend it 5 times before pushing it to the repo till you have finished the whole section and revised. I am going to perhaps perhaps not see clearly anyways before you let me know it’s ready so commit often therefore we have good history just in case one thing goes incorrect so we don’t loose your entire writing should your computer crashes.
For very early drafts, i might typically mark a pdf up and deliver it for you or we would stay together and undergo a printed part where I’ll mark up things once we get. In a choice of situation, We anticipate that you’ll upgrade things when you look at the repository a short while later. In phases, after the content is really a bit stable, i shall typically begin modifying things in the repository. This may often be through making feedback into the text. Making it easier for me personally to go out of feedback 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 might be some elements of the paper still under construction, e.g., figures you nonetheless still need getting or even a citation you nonetheless still need to locate. For those, have actually a TODO macro defined such that people can certainly spot what’s left to complete:
- To ensure we are able to demonstrably see figures that have to be dual checked, surround all figures with the\checkNum macro that is following. Be sure to take away the color through the macro before publishing. Credits: once again, this will be another trick we discovered from TU Darmstadt pupils.
If you’re alone focusing on the repository, there are not any odds of disputes. But, 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 modifications to your neighborhood repository, make yes to commit your present changes first then do git pull –rebase . perform some same before pushing modifications. This decreases the likelihood of us getting unneeded merge conflict communications and offers a cleaner history for people (for example., 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 a peek at the link have not strictly implemented this. This makes it simpler to versions that are diff resolve conflicts. We will you will need to implement this myself in the years ahead.
- We don’t claim to end up being the world’s writer that is best, but i’ve a few pet peeves:
- be sure 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 just keep doing the same task over and once again; 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 concisely you are able to say one thing the greater. If you’d like more terms, utilize numerous sentences. You’ll want to just take 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 are usually particular them another reason to shoot your paper down as it is.. don’t give.
- To prevent typing a long list (plus it’s hard to remember now), Claire Le Goues’ post has good recommendations on composing design. Nevertheless, note exactly how she prefers obtaining the whole paper in one file and I also don’t ? – thus, each advisor’s individual choices.
- Generally speaking, be ready to do numerous iterations on the paper. We may find yourself re-organzing things many times. Show patience and present your self time that is enough regarding the due date for those iterations.
keep in mind my PhD consultant, Ric Holt, for the words “big picture”. They truly are now etched within my mind. do they suggest? You always wish to inform your reader just what the picture that is big. What’s the context associated with the nagging issue you will be coping with? precisely what you doing? Why should they worry about what you are really doing? Who’ll benefit from the outcomes? just just how can the total outcomes ? a paper that is good actually leaves your reader wondering about some of these points. Preferably, the introduction should already respond to a lot of these “big picture” concerns without necessary overwhelming your reader with tons of low-level details or part “stories”.
Associated with big images, I’m a fan that is big of numbers a numbered or labelled example steps for the methodology or perhaps the the different parts of a framework, as an example. These figures can then be referenced in the text, while making 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 🙂
Ideally, make your experiments such it is very easy to re-run them and upgrade the outcome within the paper as required.
For numbers, plots etc., the way that is best to get this done is always 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 (I really don’t simply because We never ever attempted it perhaps maybe not because We have such a thing against it), you then currently guarantee these are typically always as much as date.