It really is more focused on paper structuring and collaboration, instead of writing that is lower-level. It is really not supposed to be a golden standard in in whatever way, and I also do not declare that my choices will be the right method to do just about anything. This is certainly primarily intended for my students – particularly, to prevent being forced to duplicate myself each time we begin working with a student that is newprompted by Claire Le Goues’ post a bit right straight back). But, if you discover this information of good use, or desire to use a setup that is similar please just do it! I shall 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 every single brand new paper we focus on, please create an exclusive GitHub repository under the following name paper to our GitHub organization- – . 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 have actually a venue that is concrete head. If that’s the case, utilize some descriptive expression. For instance, if we had been focusing on extracting configuration constraints, the repo name could be paper-nadi-config-constr . Credits: we learned this naming strategy inside my time at TU Darmstadt and found it quite of good use, since typically team’s GitHub organization could have a mixture of paper repos, rule repos, grant repos etc. Having some fixed prefix for documents made them more straightforward to spot.
We shall compose all documents utilizing LaTeX. In the event that you don’t understand LaTeX, now could be the time for you to discover.
Whenever we are targetting a conference that is specific remember to have the right template for the meeting. it will be this kind of shame to obtain a desk reject, as a result of utilising 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 LaTeX that is main file main.tex and keep it when you look at the directory that is main. Make an independent tex apply for each area within the paper, and organize the directory as follows (this example assumes our company is utilizing the ACM template):
The >main.tex file as required. That is will be a good example of just just what main.tex seems like:
- Please do not include any files that are generated the git repository ( e.g., .blg, .log, .aux etc.). And also this includes the main.pdf file.
We shall collaborate through the repository that is git. So please please please commit regularly and push the repo. You don’t 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 perhaps 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 early drafts, i might typically mark up a pdf and deliver it to you or we’d stay together and proceed through a printed part where I’ll mark up things once we get. In either situation, We anticipate you will upgrade things when you look at the repository a short while later. In phases, after the content is really a bit stable, i am going to typically begin things that are editing the repository. This can frequently be through making remarks into the text. Making it easier in my situation to go out of reviews as well as for one to answer them if required, also have the following macros defined (clearly, alter colors as required). In case a remark had been 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 find. Of these, a TODO macro defined such that individuals can quickly spot what’s left doing:
- To be sure we could demonstrably see numbers that have to be double checked, surround all numbers with the\checkNum macro that is following. Remember to take away the color through the macro before publishing. Credits: once more, this is certainly another trick we discovered from TU Darmstadt students.
If you’re alone focusing on the repository, there aren’t 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 take to pulling modifications to your repository that is local yes to commit your present changes first then do git pull –rebase . Perform some same before pressing modifications. This decreases the likelihood of us getting unnecessary merge conflict communications and offers a cleaner history for all of us (for example., no unneeded merges).
While i’ve maybe not strictly implemented this myself thus far, i do believe it really is a smart idea to have each sentence in a different line (Sebastian Proksch at TU Darmstadt, now at U. Zьrich used to adhere to this). This will make it more straightforward to diff variations and resolve conflicts. I will make an effort to implement this myself in the years ahead.
- I don’t claim to end up being the world’s best journalist, but i’ve a few pet peeves:
- be sure you understand when you should 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.
- When you yourself have a sentence that’s four lines very long, chances are confusing and hard to comprehend. Break it down. The greater concisely you can easily 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 loose visitors by forcing them to return and read each sentence or paragraph twice. Make their life easier. Reviewers are generally particular them another reason to shoot your paper down as it is.. don’t give.
- To avoid typing an extended list ( and 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 iterations that are multiple the paper. We would find yourself re-organzing things times that are several. show patience yourself time that is enough regarding the 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 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 problem you may be working with? What precisely you doing? Why should they value what you yourself are doing? Who’ll gain from the outcomes? Just how can the outcomes ? a good paper never ever actually leaves your reader wondering about some of these points. Preferably, the introduction should currently 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”.
Pertaining to big images, I’m a big fan of overview numbers that offer a numbered or labelled example actions for the methodology or even the the different parts of a framework, for instance. These figures can then be referenced in the text, and work out life a great deal easier for the reader. In addition they force you to compose in an even more way that is structured. Examples: Figure 1, Figure 1, or Figure 1. Notice the way they Figure 1 🙂
Preferably, you need to make your experiments such them and update the results in the paper as needed that it is easy to re-run.
For numbers, plots etc., the way that is best to achieve this will be have a script for reproducing the graph. So we can essentially 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.