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 puny, non-obvious details (e.g. checking in a copy of the reviews to svn) that make our lives lighter 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 sleekly and Two) expectations for what needs to be done to produce a high quality paper. This 2nd category is especially significant 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 abilities I will help you develop as we craft the text and you will proceed to hone those abilities for your entire carreer. The idea behind this document is get the effortless, mechanical stuff out of the way quickly so you can concentrate your time on learning how to write.
Very first things
Technical writing is a skill that, like most abilities, almost anyone can acquire. It is not, however, a skill that most computer science graduate students get much indeed good practice at during their undergraduate education. It is also an activity that many computer scientists do not particularly love. Nevertheless, it is a skill that you must become versed at if you are to be a successful researcher. There is no way around this.
Also, like many abilities, there are a good many good books on the subject. You should read the following:
“Style: Lessons in Clarity and Grace” by Joseph M. Williams and Gregory G. Colomb. This book is truly excellent. It’s helped to improve my writing a excellent deal. It is also the text for Lawrence Saul’s excellent technical writing course. You should take that course too.
“The Science of Scientific Writing” by George D. Gopen and Judith A. Swan. An excellent complement to “Clarity and Gracy”
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.
“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 .
“A Referee’s Prayer” 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 Two) 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.
Crafting a Paper
Know Your Reader/Reviewer
It is significant to understand your audience when you are writing a paper. The very first audience for any paper is the conference program committee or the journal’s editors. Fortunately, you know a lot about these kinds of people, because, for the most part, they are people like you, your colleauges, and your advisor.
Consider the characteristics of an ideal reviewer.
She has ample time.
She cautiously reads each word.
She looks over the cited papers to gather context.
She is an pro in the field.
She is open-minded.
She gives you the benefit of the doubt.
She is able and willing to put aside her predjudices and preconceptions about the research area.
She takes careful notes.
She consults with a local pro, if she is unacquainted with the area.
She goes back to review parts of the paper she did not understand.
She wants the most interesting, arousing papers for the conference, no exceptions, no compromises.
She works hard to identify and understand the ideas you are attempting to express.
Writing for such a reviewer is effortless, because the reviewer is willing to put in a lot of work to understand what you’ve written. These reviewers (or something like them) exist, but they are in the minority. If you want to get your paper accepted, you should target less idealized reviewer.
She is impatient.
She is reading as prompt as possible.
She is very skeptical.
She leaps to conclusions.
She is tired.
She is dissipated.
She has 15 more papers to read.
She is looking for a reason to stop reading and reject your paper.
She thinks she understands the area, but doesn’t.
She has little expertise in the area but was assigned to the review the paper anyway.
She does not read the related work.
She is looking for a reason to reject your paper because she works in the same area.
She is looking for a reason to reject your paper because she has a paper under obedience to the same conference and only so many papers will get in.
She is looking for a reason to reject your paper, so she can get her review done and budge on to another paper.
If something isn’t clear, she skips it and moves on.
After the paper is accepted, the audience switches from the program committee to your technical community. While those readers are not challenging with you for conference publication slots, many of them are just as tired, dispelled, skeptical, impatient, and apt to leap to conclusions.
If your work is to have the most influence possible, the widest possible audience must be able to read and understand it. That means your paper must hold their attention in the face of exhaustion, boredom, and distraction and convey your ideas despite their predjudices, misconceptions, and preconceptions.
Writing a paper that can accomplish this is challenging and it requires a fine deal of work. Fortunately, however, the switches you need to make in order to reach the less-than-ideal reader will also result in a paper that gets your ideas across and keeps your reader (regardless of how tired they are) engaged.
Why, What, and How
A good systems paper must reaction three questions about the research projectit describes: Why is the research project interesting and significant? What does the research project accomplish/? and How did the project accomplish it?
We use pdflatex and bibtex to typeset papers. It produces nice-looking output and is cross-platform. Spandex is a sophisticated 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 superb guides to spandex, but google does a pretty fair job of solving specific problems. As always, your fellow grad students are an excellent resource.
If you need to create a fresh paper, please embark by ‘svn copy’ing a latest paper or trunk/Papers/PaperTemplate. Please stick to the organization of files that is there. It’s nimble enough to accomodate any particular format that a conference requires and it includes the collected wisdom (and macros) we have accumulated about creating easy-to-manage, good-looking papers.
You can edit the spandex source using any text editor you like, but it needs to save text files with Unix-style line cracks and it must play nicely with svn, emacs, and vi. There are sophisticated WYSIWYG editors for Spandex. 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 git versioning system to track revisions of our papers (and most everything else we produce in the course of our research). There’s slew of documentation about both on the web. SVN and git provide the beginning of good version control but not the end. We also go after several other rules to keep things running sleekly:
Check in early and often. SVN/git serve as backup mechanisms as well as version control systems.
Everything needed to build the paper should be checked into git/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 spandex or bibtex should be checked in (e.g. aux. bbl. log. pdf).
Typing “make” in the paper directory should produce a file called paper.pdf. You should not check in paper..pdf.
SVN/git does not provide a strong notion of locking: they will joyfully permit two people to make incompatible switches to the line of the same file. This will result in conflicts when one of the authers does an update. These conflicts can cause evident and non-obvious switches to the text that no one intended. To avoid these problems we use an ad hoc e-mail-based locking system:
When you commenced 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 possessor field next to it. Share this document with all the authors of the paper.
How to be an author on a paper
Before the deadline
You should be available to work (at school) on the paper for, at least, the Trio 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.
If you have a conflict with #1, you need to let me know at least Two 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, Rapid, 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.
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
You should be available during the rebuttal period to work on the rebuttals. This will typically not take more than a duo hours a day during the rebuttal period unless you are very first author. There are exceptions, however, so you should plan on being available.
After (hopefully) acceptance:
Work with the other authors to grind the paper for the camera ready version.
Here, more than ever, the we need the paper to look good and supply the message we want it to. People should be affected when they look at our papers, and we will spend a lot of time refining how the paper looks, sprucing up figures, etc.
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 very first author know.
You should not schedule anything that conflicts with the conference without checking with me very first. Going to conferences is an significant for your professional development, especially when you’re work is being introduced.
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.
You should be well rested for and attend the talk.
Being very first author on a paper
Being the very 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 very first author comes with a fine 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 reaction for it.
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 outside collaborators.
Prepare the skeleton of the paper. This means creating a fresh directory in SVN/git repo with an suitable name. We use the naming convention <year><conference>-<topic> For example: 2010ISCA-Foobar. You can create the skeleton by copying another latest paper, but undress out all of the unrelated text. Make sure it builds from a clean checkout. Send out the SVN/git information to the rest of the authors.
Set up email notifications for commits: From the repo home page on github, select “settings->Web Hooks and Services -> Add Service -> Email.” Come in either “Storage NVSL ” or “Gadgetron NVSL ” depending on whether the paper is related to storage/NVMs or Gadgetron. Leave the “secret” blank.
Ensure that the spandex source for the paper conforms to the formatting requirements for subordination to the conference. This means that the paper should build and conform to the formatting requirements of the conference. If the conference provides a .cls file, we should use it. However, please don’t import any templates that the conference provides, they are not usually helpful.
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. If the deadline is not clear, it is your job to find out when it is.
Know how many pages are permitted and what the rules are (e.g. does the page count include the references?).
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 Two days ahead of time about the abstract and title.
Distribute the account and login information for the paper subordination site to the other authors of the paper in our group. I’ll distribute it, as needed, to people outside our group.
Collect and come in author and conflict of interest information for the paper. If we have faculty collaborators be sure to give them at least Trio days to react to your request for conflict information.
Select a set of topic areas for the paper, and discuss them with me before coming in them on the conference web site.
Make sure you have all the other information that the conformity site requests. If you need extra information, let me know.
Unless we discuss otherwise, you will be responsible for subjugation. This means that at about T-minus 1 hour from the deadline, you should have the conformity site loaded up in a web browser and be logged in. You should submit drafts regularly up until the deadline just to be safe.
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.
You are responsible for ensuring the paper submitted on time.
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’ or ‘git tag’.
At rebuttal time:
Rebuttals are chance that some conferences provide to react to reviews. Not all conferences provide the chance for a rebuttal. You should know whether your target conference does.
Be aware of the rebuttal period and send out a reminder email to the authors Two days before.
When the review period starts, check the web site regularly for the reviews to become available. Proceed to check regularly via the rebuttal period. Late reviews may show up.
Send out a copy of the reviews and a link to them. It is significant 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.
Check in a copy of the reviews to SVN.
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.
Send out the summary.
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.
Iterate on the rebuttal with me and the other authors.
You are responsible for making sure the rebuttal is submitted on time.
After (hopefully) acceptance:
Once you receive the author packet, email the other authors with information about when the camera-ready version is due.
Reformat the paper to meet the specifications, and check it in. Let everyone know how we stand with respect to length.
Keep track of any paperwork (e.g. copyright forms) that need to be printed/signed/faxed. Take care of it.
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.
You are the lead on getting the paper into camera-ready form (see below).
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 forearm side of the main page (two lines is even better).
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.
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 conformity, so be sure to begin this discussion in slew of time.
Preparing the camera-ready version of a paper
The standard of grind on the camera-ready version of your very first paper is very likely 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 bearing 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 thrust for completing the camera-ready version can involve fairly a bit of work, sometimes almost as much as the initial obedience. 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 conformity time. There will also be a excellent deal of fine tuning the wording and appearance of the paper.
There are many steps to preparing the camera ready version of the paper.
Put the paper into the final subordination format as given by the author packet. Typically, there will be a space for keywords on the very first page as well as a copyright notice. If they don’t display up, you may be doing something wrong, so come check with me.
You have not looked the paper in some time, so your eyes will be fresh. Use this uncommon chance to read the paper critically from commence to finish. Can you tighten the language? Can you improve the argument? Do questions leap out at you? Do you have trouble understanding a figure? Mark up a copy of the paper with the fixes, but don’t get dispersed by fixing them.
After reading through the paper entirely, fix the problems you found.
Are there page numbers? Usually, they are not permitted on camera-ready submissions. Check the instructions to be sure.
Consider making large-scale switches 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 scrape given what you know now. This is the time to make these large switches.
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 extra workloads, updating graphs, etc.
Update and check all the numbers given the paper. This means recalculating them all based on the latest data.
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?
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 broad enough to be distinguished from one another? Are the lines in line graphs different enough to lightly identified? Fix any problems you find.
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.
Are all the figures, captions, graphs, and tables, the same width as the columns they are in? They should not be narrower or broader.
If needed confer with me about selecting key words for the paper. Add them to the paper using the suitable macros (they will be defined as part conformity style file).
Proofread, proofread, proofread! Typos make you look bad, so you don’t them enshrined forever in the paper.
Consistency check. Are all example 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 puny inconsistencies, just fix them. If there are more broad spread problems (i.e. different people are consistently using different spellings or names).
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 spandex source and attempting lots of things. Keep at it.
If there are line violates in the title are they where you want them? Does the title look good?
Ask each author how they would like their name to show up and with what affiliation. In particular, do they use a middle initial?
Does the author list look good? Are they too crowded? Are their strange coincidental alignments inbetween names on different lines that look awkward?
Once all the content is stationary, you should concentrate on making the paper as a entire look good. This means beginning on the very first page and looking for all types of visual/typesetting problems listed below. Fixing them will take a bunch of messing around with the spandex and fixing some will cause others. It’s an iterative and slow process, but is necessary to make the paper look its best.
Large gaps inbetween paragraphs
Section titles on their own at the bottoms of columns
Excessive gaps or white space.
Excessively narrow spacing inbetween figures and text. Can you tell where the caption completes an the text embarks?
Pages downright packed with figures.
Figures or tables on the very first page.
Once all this is done, send out a draft the authors who are managing the final subordination, and ask for comments. Iterate until everyone’s glad.
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.
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 very first author on a paper, you are responsible for knowing and meeting the deadline and other requirements for subordination. 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
Defining and Using Fresh Terms
Introducing fresh terminology or including technical shorthand in a paper can help clarify your writing, but it can also add complexity and add to the mental blast of your reader. Fresh terms include any word or phrase that you define and assign a specific meaning to.
Fresh terms and technical shorthand falls into three categories: Contribution terms, simplifying terms, and technical shorthand.
These are terms you define to make the paper lighter to understand. This include acronyms and abbreviations. For example, here’s a definition of several fresh terms from one of our papers (fresh terms in italics):
This partitioning gives rise to four fresh types of pointers: Pointers within a single NV-heap (intra-heap NV-to-NV pointers ), pointers inbetween two NV-heaps (inter-heap NV-to-NV pointers ), pointers from volatile memory to an NV-heap (V-to-NV pointers ), and pointers from an NV-heap to volatile memory (NV-to-V pointers ).
Defining these terms has pros and cons. On the positive side, it provides a useful shorthand for refering to sophisticated ideas. On the negative side, fresh terms require the reader to reminisce fresh, unacquainted vocabulary in order to understand the rest of the paper. That is a potential distraction.
In this case, the advantages outweigh the disadvantages, because the paper goes on to use the terms repeatedly, and repeating a phrase like “pointers from an NV-heap to volatile memory” would be more distracting.
This paragraph also gives the reader some help by cautiously choosing the terms so they have structure. They all have toughly the same structure, so the reader can group them together lightly in her mind. They are also built from well-known terms (“inter” and “intra”), terms that have been used earlier in the paper (“NV”), and common idioms (“X-to-Y”).
You can make simplifying terms lighter on your reader in several ways. Very first, hyphenate, and capitalize the term the same way every time you use it. Spandex macros are useful here. 2nd, use it consistently a single part of speach (noun, verb, adjective, etc.) Ultimately, once you define the term, you should use it every time you refer to the idea or object it represents. Otherwise, the reader may believe you are introducing a fresh concept, leading to confusing. This last rule applies especially to acronyms.
Contribution terms name a contribution or key idea of your work. Contribution terms are usually simplifying terms, but they may also be novel phrases (“liquid types”), acronyms (“Metal file systems”), puns (“eNVy”), or terms from the real world or popular culture (“Paxos”).
Choose these terms cautiously — if your research is successful, they may become widely used. They should be concise, catchy, effortless to say/pronounce, and, preferably, unique (so your work will not be confused with someone else’s).
For example, here is the definition of Liquid Types :
We present Logically Qualified Data Types. abbreviated to Liquid Types. a system for automatically inferring dependent types pre- cise enough to prove a multitude of safety properties, thereby allow- ing programmers to reap many of the benefits of dependent types without paying the powerful price of manual annotation.
“Liquid Types” is an fine contribution term because its joy, corresponds harshly with its technical meaning, and is something lik an acronym for the longer and less catchy “logically qualified datatypes.” It so catchy, that even however I know very little about programming languages, I recall the name “liquid types.”
The paper puts the term to superb use, too: It refers to “liquid types” repeatedly and builds a vocabulary of related simplifying terms around the word “liquid” (e.g. “liquid refinements” and “liquid qualifiers”). It provides a coherent framework for describing and discussing the ideas the paper presents.
Technical shorthand phrases, expressions, or symbols show up in technical contexts, but not typically in prose. For example, “write()” is a useful way to refer to the write system call.
The advantage of technical shorthand terms is that they are succinct descriptions of elaborate ideas. The disadvantage is that they are not words, so they interrupt the flow of the text. As with simplifying terms, if you are going to a chunk of technical shorthand many times, the costs very likely outweigh the benefits. If you are going to refer to it just once or twice, it is better use a longer, prose description (e.g. write system call).
This is a list of things to check for when reading over your paper. These are common problems I spend a lot of time providing feedback about. Please address these on your own before your paper goes to me or the technical writer.
Is the most significant information introduced early in the paper, section, or paragraph? In all cases, the most significant thing should come very first. Don’t “bury the lead” by hiding significant information half way through. Readers skim all the time. Make it effortless for them.
Have you eliminated all your passive voice? If some remains are you ready to argue vigourously for why it should remain?
Do you define your acronyms once and only once and, once they are defined, use only the acronymns from then on?
Do you consistently use the terms you define? Once you have gone through the effort of defining a term and making your reader learn what it means, you should use it.
Do you use the terms you define at all? Are they necessary? Each fresh term is something that the reader must learn to recognize. IF you only need to refer to something once or twice, it may not be worth defining a term for it?
Do you create fresh terms to highlight significant ideas and make it lighter for the reader to understand what you are telling? Creating fresh terms can given the reader a treat on significant concepts and “families” of terms can highlight significant differences (e.g. “inward loop” vs. “outer loop”).
If you create fresh terms, are they effortless to pronounce? Fresh terms should make it lighter to discuss and name components or ideas. Hard-to-pronounce terms are not effortless to use.
This is an incomplete style guide for the group. Please go after it.
No passive voice. This is not a fully hard rules but you should be able to passionately defend any passive voice in the paper.
Figure and title captions are accomplish sentences.
1(a)”, not “Figure 1a” or “Figure 1-a”. The ‘
‘ is a non-breaking space in tex.
\cite“, not “some work \cite\cite\cite“
There must be a space inbetween a number and its units: “The experiment took Ten
s” not “10s” or “10-s” or “10s”. This page has useful pointers on the usage of numbers and units (overlook what it says about hard drive capacity). The only exceptoins are “\x<>” and “%”. No space for those.
In section headings, only the very first word is capitalized.
Use the \figtitle<> macro at the beginning of your captions for figures and tables. Only the very first word in the figure title is capitalized.
use $\times$ instead of ‘x’ for multiplicative spectacle increases. There should be a macro for this: \x<>. If there is not, add one to defs.tex.
Uncommonly, if ever, use semi-colons to form compound sentences.
There is no comma before the conjunction in a compound noun or verb: “He quickly circumnavigated and then saved the world” not “He quickly circumnavigated, and then saved the world.”
There is a comma before the conjunction in compound sentences: “He quickly circumnavigated the world, and he was blessed about it.”
“the experiment was Ten\x<> swifter” not “x” or “X” and not “Ten
Every section must have at least one introductory paragraph. You should not have a section heading followed instantly by a subheading. You must provide an intro paragraph
No contractions: “cannot” instead of “can’t”, “did not” instead of “didn’t”
“Data” is plural. So is “metadata”. There is no hyphen in “metadata”.
“write-only” not “write only”
Once an acronym is defined, it should always be used in place of the phrase it represents.
Spell out numbers less than Ten and “round” numbers less than 100. E.g: “Five programs executed fifty instructions each” “Five programs executed 74 instructions each” “five programs executed 1042 instructions each”
Includes commas in numbers larger than Ten,000. e.g: “He ate 1000 hot dogs” “He ate Ten,000 hot dogs”
“cannot” instead of “can not”
Function calls should be typeset with \fc<>: e.g. \fc instead of “memcpy()”
“K” “M” etc are cannot be used as shorthand except in the context of units: e.g.”kB” is ok. “10K lines of code” is not.
Avoid first-person plural pronouns (i.e. “we,””our,”, etc.) when possible. Usually it can be eliminated. Other possibilities for nouns in places of these are “the paper” “this section” etc. but see the next bullet.
Attempt to avoid refering to “this paper,” “this section,” etc. they are not interesting actors in a sentence. However, getting rid of them can lead to awkwardness or, even worse, passive voice. Use them in moderation.
Preparing Graphs and Figures
Graphs and figures in papers need to be lightly legible and effortless 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 purpose 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 emerge 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 lightly 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.
The caption is an significant 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. Recall, 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.
Things to consider/recall when building a graph:
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.
If there is more than one set of bars or line, include a legend.
Make sure the names and labels in the legend, bar labels, etc. are meaningful and that they match what is used in the text.
Do not include a title on your graph. The caption serves this purpose.
You should not generally use a log scale unless you are attempting to showcase that something is exponential or you are just interested in orders of magnitude.
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.
It can be useful to prototype graphs in excel, but excel is not a superb 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.
Think critically about your graph. Does it make the point you are attempting to convey? Could that point be made more visible? 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 effortless for the reader to verify? Are the two bars close together?)
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 treating data sets with many thousands of points. Ploticus works well for bar graphs. Neither of these programs is terribly effortless to use and they both have slew of warts, but this is the case of all graph drawing systems. We have standardized on these two, to make it lighter 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 good 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 spandex
The relationship inbetween the size and form of the pdf of graph or figure and how it emerges in the paper is non-intuitive. The macros we use to include figures and graphs in spandex specify a immobilized width, and spandex will scale the pdf to match that width. This means that the height of the figures and graphs is immobile and its height is determined by the figures aspect ratio (i.e. the ratio of it’s height to width). For example, 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 example, if you just make the figure broader, spandex will shrink it more, and the fonts may become difficult to read.
If you want the figure to show up 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 in the text, this will cause a spandex 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 showcase up as missing citations in the submitted paper.
Working With a Technical Writer
In some cases, we may hire a technical writer (TW) to help with writing the paper. The TW will mostly concentrate on grammar, mechanical, style and presentation issues that are not CS-specific. I work with the TW to ensure that his or her work reflects our standard practices. Using a TW is an effortless way to improve the quality of our papers without much effort on our part.
Working with TW does require some effort, tho’. Below are the guidelines for working with the TW:
Be courteous. The TW is an independent contractor and if working with us is not reasonably pleasant practice, they may not wish to work with us in the future. This will negativey influence the entire group.
Incorporate all of the TW’s edits. The TW will not always be correct, but he or she has a fine deal of practice editing prose. When you receive comments from the TW, you should incorporate and/or flag all of the switches they propose. For flagged switches, we can discuss them and determine what to do with them.
Get a draft to the TW on time. The TW does eat, sleep, and breath research like we do, so it is unreasonable to expect the TW to make a last minute pass over the paper in the hours before a deadline. We will set a deadline for getting the TW a draft. You should do everything in your power to make that deadline.
The TW does not need a accomplish draft of everything to provide useful comments. If everything but the results section is ready, send it along with a note explaining that the TW should skip that section.
You should only send text to the TW that you are mostly glad with. The TW process should come after we have determined on the general flow for the paper and you’ve gotten the text into pretty good form, otherwise the benefits of their work will vanish when we make substantial revisions.
Our process for working with a TW is a work in progress. Please let me know if you have any thoughts.
Related video: Black Men and Public Space, by Brent Staples (Analysis & Interpretation)