# The Nuts and Bolts of Writing Papers

By Steven Swanson (swanson@cs.uscd.edu)

Papers are your primary work products as a researcher, so it's in your interest to make sure they are of high quality.  This document describes the practical aspects of writing papers.  It details your responsibilities in the process (depending on your role) and what you need to do and when.  This includes many small, non-obvious details (e.g., checking in a copy of the reviews to svn) that make our lives easier before, during, and after the paper deadline.

This document covers the pratical side of writing papers. Its contents fall into two categories: 1) Useful hints for making the paper writing process go smoothly and 2) expectations for what needs to be done to produce a high quality paper. This second category is especially important because it helps make sure we are all the same page about the paper writing process, who's responsible for what, etc. If you have any questions about anything in this document please ask.

This document does not discuss how to structure a paper, craft a good introduction, or create a well-reason argument that flows well and is engaging to the reader. Those are skills I will help you develop as we craft the text and you will continue to hone those skills for your entire carreer. The idea behind this document is get the easy, mechanical stuff out of the way quickly so you can focus your time on learning how to write.

## First things

Technical writing is a skill that, like most skills, almost anyone can acquire.  It is not, however, a skill that most computer science graduate students get much really good practice at during their undergraduate education.  It is also an activity that many computer scientists do not particularly enjoy.  Nevertheless, it is a skill that you must become proficient at if you are to be a successful researcher.  There is no way around this.

Also, like many skills, there are a great many good books on the subject.  You should read the following:
1. "Style: Lessons in Clarity and Grace" (10th Edition)  by Joseph M. Williams and Gregory G. Colomb.  This book is really excellent. It's helped to improve my writing a great deal.  It is also the text for Lawrence Saul's excellent technical writing course.  You should take that course too.
2. Strunk and White's "The Elements of Style" is also good, but much drier.  However, it provides good answers to many very practical questions about what should be capitalized where, etc.
3. "An evaluation of the ninth SOSP submissions or how (and how not) to write a good systems paper" by Roy Levin and David D. Redell. It provides a practical set of questions to ask yourself while writing papers. It's available here.
4. "A Referee's Plea" by Mark Allman. More good advice or writing sound papers from a reviewer's perspective. It's here.
Reading these will not make a good writer overnight, but it will provide you with two things:  1) Heaps of very practical advice that will significantly improve your writing and 2) a different perspective on writing:  These books formalize and name many aspects of both good and bad writing.  Having good names and definitions for things is basis for reasoning and thinking about them rigorously, which is what you should eventually be able to do about your writing. Having this skill may make writing more palatable to you: It makes it less of a craft and more of a science. These books will give concrete, explanations for why some sentences and paragraphs "just seem better." Once you understand those explanations, you can use them as guidelines to make other sentences better. Of course, there is still craft involved, and you need to master that as well.

## Software

We use pdflatex and bibtex to typeset papers. It produces nice-looking output and is cross-platform. Latex is a complex and powerful system, but the basics are not too complicated. We have a standard paper skeleton we use that makes text look like it's a paper. You'll pick up the finer points pretty quickly. I've not found any books that are especially great guides to latex, but google does a pretty fair job of solving specific problems. As always, your fellow grad students are an excellent resource.

You can edit the latex source using any text editor you like, but it needs to save text files with Unix-style line breaks and it must play nicely with svn, emacs, and vi. There are sophisticated WYSIWYG editors for Latex. You are welcome to use, them but "real" version of the paper should be built by a makefile, since it's infrastructure that is available to everyone.

We use the SVN or CVS versioning system to track revisions of our papers (and most everything else we produce in the course of our research). There's plenty of documentation about both on the web. SVN and CVS provide the beginning of good version control but not the end. We also follow several other rules to keep things running smoothly:

• Check in early and often. SVN/CVS serve as backup mechanisms as well as version control systems.
• Everything needed to build the paper should be checked into CVS/SVN (this includes .tex, .bib, and .sty files, e.g. as well as the .pdf's for figures and graphs). Nothing that is generated by latex or bibtex should be checked in (e.g., .aux, .bbl, .log).
• Typing "make" in the paper directory should produce a file called paper.pdf. You should not check in paper..pdf.
• SVN/CVS does not provide a strong notion of locking: they will happily allow two people to make incompatible changes to the line of the same file. This will result in conflicts when one of the authers does an update. These conflicts can cause obvious and non-obvious changes to the text that no one intended. To avoid these problems we use an ad hoc e-mail-based locking system:
• When you started editing a file send an email with a subject line like "lock(foo.tex)" to the authors of the paper..
• When you are finished, check in and then send the message "unlock(foo.tex)"
• As an alternative, you can set up a google spreadsheet with a line for each file and an owner field next to it. Share this document with all the authors of the paper.

## How to be an author on a paper

1. You should be available to work (at school) on the paper for, at least, the 3 weeks prior to the deadline and you should plan on working almost all day every day (including night and weekends) on the paper during the last week.  In some cases, all of this time will not be necessary, and we will sometimes take days off to unwind, but this should be your expectation as far as planning.
2. If you have a conflict with #1, you need to let me know at least 2 months in advance of the paper deadline so we can adjust our timeline appropriately. You should assume that every year we will target ISCA, MICRO, ASPLOS, FAST, SOSP, OSDI, and any other conference you have submitted to previously, so be aware of those deadlines.  If you are wondering if we are targeting a conference, ask. Deadlines are set at least 6 months in advance for all these conferences.
3. As an author on the paper, you should be willing to do whatever needs doing to get a paper out the door, even if it is not "your job." Research is a team sport.
During the rebuttal period
1. You should be available during the rebuttal period to work on the rebuttals.  This will typically not take more than a couple hours a day during the rebuttal period unless you are first author. There are exceptions, however, so you should plan on being available.
After (hopefully) acceptance:
1. Congratulations!
2. Work with the other authors to polish the paper for the camera ready version.
3. Here, more than ever, the we need the paper to look good and deliver the message we want it to.  People should be impressed when they look at our papers, and we will spend a lot of time refining how the paper looks, sprucing up figures, etc.
4. Check out the section on camera-ready papers below. If you notice that something doesn't measure up to that list, fix it or let the first author know.
The conference:
1. You should not schedule anything that conflicts with the conference without checking with me first. Going to conferences is an important for your professional development, especially when you're work is being presented.
2. If you attend the conference, the university (i.e., my grants) will, in most cases, cover your transportation, lodging, and food for the duration of the conference.  You are welcome to stay longer but the extra hotel etc. is on your dime.
3. You should be well rested for and attend the talk.

## Being first author on a paper

Being the first author on a paper means that you are the lead student on the paper.  This is good for you professionally, since you will be the student most closely associated with the paper. However, being first author comes with a great deal of responsibility. In fact, by default, everything about the paper is ultimately your responsibility. During the course of writing the paper other authors will take over certain aspects of the paper's writing and technical content, but it's your job to track deadlines (e.g., submitting copyright forms, collecting conflict lists, making sure that a shepherd's requests are met on time) and make sure that things are finished on time. This means keeping your co-authors up-to-date about what needs to be done and following up with to make sure things are on track. I repeat: You are responsible for getting all these things done. If they don't get done, you will be on the spot to answer for it.

Before submission:

1. At all times, forward any emails you receive about the paper to the other authors in our group. I will forward them as needed to the others.
2. Prepare the skeleton of the paper. This means creating a new directory in SVN with an appropriate name. We use the naming convention <year><conference>-<topic> For example: 2010ISCA-Foobar. You can create the skeleton by copying another recent paper, but strip out all of the unrelated text. Make sure it builds from a clean checkout. Send out the SVN information to the rest of the authors.
3. Ensure that the latex source for the paper conforms to the formatting requirements for submission to the conference.
4. Be aware of the conference deadline, including the time and time zone at which the paper is due.  Know when it is due in local time.
5. Know how many pages are allowed and what the rules are (e.g., does the page count include the references?).
6. Be aware of the abstract deadline (including local time), if there is one.  Ensure that the paper is registered and an abstract is submitted in time.  This means conferring with me at least 2 days ahead of time about the abstract and title.
7. Distribute the account and login information for the paper submission site to the other authors of the paper in our group.  I'll distribute it, as needed to people outside our group.
8. Collect and enter author and conflict of interest information for the paper.  If we have faculty collaborators be sure to give them at least 3 days to respond to your request for conflict information.
9. Select a set of topic areas for the paper, and discuss them with me before entering them on the conference web site.
10. Make sure you have all the other information that the submission site requests. If you need additional information, let me know.

At submission:

1. Unless we discuss otherwise, you will be responsible for submission.  This means that at about T-minus 1 hour from the deadline, you should have the submission site loaded up in a web browser and be logged in.   You should submit drafts regularly up until the deadline just to be safe.
2. You should be submitting the paper from a machine on you are building the paper.  There should not be emailing the paper to yourself or otherwise shuffling files around.  You need to be able to do 'svn update'  'make' and within a few seconds be uploading the paper to the web site.  Practice this ahead of time, and make sure you have your ssh keys setup so svn doesn't ask you for a password.
3. You are responsible for ensuring the paper submitted on time.
After submission:
1. Once the final version of the paper is submitted, ensure that the paper builds correctly from a clean checkout (make test_build) and add the submitted pdf with a name like 'submitted_to_isca_2009.pdf' and commit it.  Then tag the paper source with a similar name using 'svn copy'.
At rebuttal time:
1. Be aware of the rebuttal period and send out a reminder email to the authors 2 days before.
2. When the review period starts, check the web site regularly for the reviews to become available.  Continue to check regularly throughout the rebuttal period.  Late reviews may appear.
3. Send out a copy of the reviews and a link to them.  It is important that you send out a copy and not just a link, because after the rebuttal period, the reviews may no longer be available on line.  We will want to refer to them later.
4. Check in a copy of the reviews to SVN.
5. Summarize the reviews.  You want to collect the reviews by what the topic of their complaint, and then synthesize each reviewers complaint on each topic into a high-level point that we can address.  Along with each high-level point, the summary should contain the passages from the reviews along with an annotation denoting which reviewer the comment came from.
6. Send out the summary.
7. Draft a response to each of the high-level points, and send it out as well. The summary and the draft response should be sent out no more than 12 hours after the reviews become available.
8. Iterate on the rebuttal with me and the other authors.
9. You are responsible for making sure the rebuttal is submitted on time.

After (hopefully) acceptance:

1. Congratulations!
2. Once you receive the author packet, email the other authors with information about when the camera-ready version is due.
3. Reformat the paper to meet the specifications, and check it in.   Let everyone know how we stand with respect to length.
4. Keep track of any paperwork (e.g., copyright forms) that need to be printed/signed/faxed.  Take care of it.
5. You are responsible for submitting the camera ready version on time.   Caveat: The camera-ready deadline is not a hard deadline, so we will frequently be late.  You should discuss with me what our "real" deadline is for getting it in.
6. You are the lead on getting the paper into camera-ready shape (see below).
7. Create a news story on the project website announcing the acceptance of the paper. Ask another member of the group how. It should fit with three lines in the news feed on the left hand side of the main page (two lines is even better).
8. Update the canonical bibtex entry and rebuild all the web pages that include the paper. Remind Steve to do the same to the architecture home page. Ask another member of the group how.
9. Discuss submitting the paper to IEEE Micro TopPicks with your advisor. It's an annually published collection of the best papers in computer architecture. The deadline is in mid September. It takes several weeks to prepare a submission, so be sure to start this discussion in plenty of time.

## Preparing the camera-ready version of a paper

The standard of polish on the camera-ready version of your first paper is probably higher than for any document you have produced in the course of your education. This is for good reason: Finished papers are, aside from trained researchers, the only product of research. They are the enduring embodiment of the ideas we have developed. Everything else (the code, workloads, scripts, etc.) is just an artifact. The paper is what counts. It is what lasts.

The push for completing the camera-ready version can involve quite a bit of work, sometimes almost as much as the initial submission. You should budget your time accordingly. Typically, we will need to update the paper to reflect the latest results and to remedy any problems we did not have time to fix at submission time. There will also be a great deal of fine tuning the wording and appearance of the paper.

There are many steps to preparing the camera ready version of the paper.

1. Put the paper into the final submission format as given by the author packet. Typically, there will be a space for keywords on the first page as well as a copyright notice. If they don't show up, you may be doing something wrong, so come check with me.
2. You have not looked the paper in some time, so your eyes will be fresh. Use this rare opportunity to read the paper critically from start to finish. Can you tighten the language? Can you improve the argument? Do questions jump out at you? Do you have trouble understanding a figure? Mark up a copy of the paper with the fixes, but don't get distracted by fixing them.
3. After reading through the paper completely, fix the problems you found.
4. Are there page numbers? Usually, they are not allowed on camera-ready submissions. Check the instructions to be sure.
5. Consider making large-scale changes to the paper. We may have discussed this ahead of time, but even if we have not, consider how you would rewrite this paper from scratch given what you know now. This is the time to make these large changes.
6. Update all the figures in the paper with latest/best data we have for the experiment/systems the paper deals with. This may including adding additional workloads, updating graphs, etc.
7. Update and check all the numbers given the paper. This means recalculating them all based on the latest data.
8. Perform a mental sanity check on all the numbers in the paper. Do they make sense? Are they consistent with story the paper and with the story of the paragraph/sentence they are in?
9. Look critically at all the graphs on a printed version of the paper. Are things crowded together? Are the axis labels too close to the axis tic values? Are bars in graphs wide enough to be distinguished from one another? Are the lines in line graphs different enough to easily identified? Fix any problems you find.
10. Look at the drawn figures in a printed version of the paper. Are the fonts legible? Are the figures cramped? Could they be generally cleaned up? Fix any problems you find.
11. Are all the figures, captions, graphs, and tables, the same width as the columns they are in? They should not be narrower or wider.
12. If needed confer with me about selecting key words for the paper. Add them to the paper using the appropriate macros (they will be defined as part submission style file).
14. Spell check.
15. Consistency check. Are all instance of the names of workloads, machine configurations, and ideas spelled, capitalized, and punctuated consistently. In the figures, in the graphs, and in the text. If there are small inconsistencies, just fix them. If there are more wide spread problems (i.e., different people are consistently using different spellings or names).
16. Make sure that, to the extent possible, figures on the page with the text that refers to them. This can take a bunch of messing around with the latex source and trying lots of things. Keep at it.
17. If there are line breaks in the title are they where you want them? Does the title look good?
18. Ask each author how they would like their name to appear and with what affiliation. In particular, do they use a middle initial?
19. Does the author list look good? Are they too crowded? Are their strange coincidental alignments between names on different lines that look awkward?
20. Once all the content is fixed, you should focus on making the paper as a whole look good. This means starting on the first page and looking for all types of visual/typesetting problems listed below. Fixing them will take a bunch of messing around with the latex and fixing some will cause others. It's an iterative and slow process, but is necessary to make the paper look its best.
1. Large gaps between paragraphs
2. Section titles on their own at the bottoms of columns
3. Excessive gaps or white space.
4. Excessively narrow spacing between figures and text. Can you tell where the caption ends an the text begins?
5. Pages completely filled with figures.
6. Figures or tables on the first page.
21. Once all this is done, send out a draft the authors who are managing the final submission, and ask for comments. Iterate until everyone's happy.
22. After submitting the camera ready version, create a news story on the project website announcing its availability. Include a link to the paper. Ask another member of the group how, since it varies from group to group.
23. Update the canonical bibtex entry and rebuild all the web pages that include the paper. Remind Steve to do the same to the architecture home page.

## Miscellaneous Writing/Presentation Projects

At times you will need to producing things like extended abstracts, posters, etc.  It's critical that these be of high quality as well.  Just like being first author on a paper, you are responsible for knowing and meeting the deadline and other requirements for submission.  We will need to iterate on these items at least once and possibly several times.  This means you should get a draft of the item to me at least one week ahead of the deadline.

## Writing style guide

This is an incomplete style guide for the group.  Please follow it.
1. No passive voice.  This is not a completely hard rules but you should be able to vigorously defend any passive voice in the paper.
2. Figure and title captions are complete sentences.
3. "Figure~1(a)", not "Figure 1a" or "Figure 1-a". The '~' is a non-breaking space in tex.
4. "some work~\cite{foo,bar,baz}", not "some work \cite{foo}\cite{bar}\cite{baz}"
5. "The experiment took 10~s"  not "10s" or "10-s" or "10s". This page has useful pointers on the usage of numbers and units (ignore what it says about hard drive capacity).
6. In section headings, only the first word is capitalized.
7. Use the \figtitle{} macro at the beginning of your captions for figures and tables.   Only the first word in the figure title is capitalized.
8. use $\times$ instead of 'x' for multiplicative performance increases
9. Rarely, if ever, use semi-colons to form compound sentences.
10. There is no comma before the conjunction in a compound noun or verb: "He quickly circumnavigated and then destroyed the world" not "He quickly circumnavigated, and then destroyed the world."
11. There is a comma before the conjunction in compound sentences:  "He quickly circumnavigated the world, and he was happy about it."

## Preparing Graphs and Figures

Graphs and figures in papers need to be easily legible and easy to understand. They also need to look good and contribute to overall story the paper is telling. Figures and Graphs are, after the abstract and introduction, the likely parts of the paper that people will read while skimming. With that in mind, it's a reasonable goal that by reading the introduction and looking at the graphs, figures, and tables, a reader should be able to get the main point argument, contribution, and results of your paper.

For papers that will appear in conference proceedings and journals being legible and "looking good" means doing those things on the printed page, in black and white, as well as on a computer monitor. This means that both figures and graphs should only be in black and white -- not color, and not gray scale, but black and white. In addition, the fonts must be easily readable with the naked eye. The only exception is photographs, which can be in color (but should still be adjusted to look good when printed).

Since we use pdflatex, all figures and graphs must be pdfs to be included.

### Captions

The caption is an important part of the each figure and graph in the paper. Captions should both describe the graph or figure and explain what the key point of the figure or graph is. Remember, if the reader is skimming, she will likely read the captions and not much else. Therefore, the captions need to contain a succcint description of what the figure adds to the paper's story.

### Graphs

Things to consider/remember when building a graph:

1. Always label your axes with both meaningful names and units. The one exception is the horizontal axis for bar graphs in which the bar names obviate the need for an axis label.
2. If there is more than one set of bars or line, include a legend.
3. Make sure the names and labels in the legend, bar labels, etc. are meaningful and that they match what is used in the text.
4. Do not include a title on your graph. The caption serves this purpose.
5. You should not generally use a log scale unless you are trying to show that something is exponential or you are just interested in orders of magnitude.
6. The paper's directory structure in svn should contain the raw data for the graph, the script/file that generates the graph (e.g., ploticus or gnuplot), and a Makefile to generate the graph as needed.
7. It can be useful to prototype graphs in excel, but excel is not a great choice for building the graphs that actually go into a paper. It does not provide adequate control over the graph's layout and it is not scriptable.
8. Think critically about your graph. Does it make the point you are trying to convey? Could that point be made more obvious? Does the organization and structure of the graph match the discussion in the text (e.g., if the text compares two values, is that comparison easy for the reader to verify? Are the two bars close together?)
9. Think asthetically about your graph. Does it look good? Good graphs should be pretty and well-organized.

We use gnuplot and ploticus to draw graphs. Gnuplot is useful for line graphs mostly and is good at handling data sets with many thousands of points. Ploticus works well for bar graphs. Neither of these programs is terribly easy to use and they both have plenty of warts, but this is the case of all graph drawing systems. We have standardized on these two, to make it easier for students to learn from each other how to best get around these warts. There is documentation online for both, and you will learn a great deal by looking at examples that other students have created. If you are having trouble getting the output you want, ask me or another student.

### Scaling figures and graphs for latex

The relationship between the size and shape of the pdf of graph or figure and how it appears in the paper is non-intuitive. The macros we use to include figures and graphs in latex specify a fixed width, and latex will scale the pdf to match that width. This means that the height of the figures and graphs is fixed and its height is determined by the figures aspect ratio (i.e., the ratio of it's height to width). For instance, if you want to make a figure shorter, you should need to increase its width relative to its height. This can have unintended consequences: For instance, if you just make the figure wider, latex will shrink it more, and the fonts may become difficult to read.

If you want the figure to appear narrower on the page, you'll need to modify the macro used to instantiate it.

## Bibliographies and citations

We use bibtex to create bibliographies for papers.This means that in order to cite a paper, you'll need to create or download a bibtex entry for it. For consistency, use bibtex entries from the ACM portal. If the entry you need is not available, check IEEExplore. As a last resort, build the entry yourself.

If it's a paper that you cite frequently, give it a memorable and useful tag for use with \cite{}. Otherwise, you can just use whatever came with the entry.

Often, you may need to cite a paper that you don't have an entry handy for, you may not know what you are going to cite, or you may not want to stop writing and go look up the paper. In these cases insert something like \cite{foobar} in the text, this will cause a latex warning and will ensure that you must fix the problem to get a clean build. Do not say \cite{} or "[]", as neither of these will generate errors, and it's possible they will show up as missing citations in the submitted paper.