How to Write Interesting Computer Science

January 25, 2007 7:34 AM

I need help in learning how to write. Specifically, technical writing in the area of computer science. Most specifically, paper writing.

I am actively involved in computer science research. My biggest problem is writing about it. I am quite good at actually developing the problem, solving it and measurement. However when it come to writing I often find myself with the following recurring problems:

1. Most importantly -- terseness. I really have a problem expanding on what I'm trying to say. Mostly people liken my writing to reading telegrams. When I do try and expand I end up in the opposite direction where people comment that I'm explaining basic stuff and avoidable detail. Often I will hone in on the problem and solution without any regard to the other solut

2. Flow and composition -- Most of my writing reads like a users manual or a physics experiment, which, while getting me my degree, makes for extremely boring reading. I need help in developing how to make my work interesting to the reader.

I know the mantra with writing is re-write and re-vise. But I often find myself throwing away 3 or 4 copies of written material because they just aren't conveying what I want them to convey. In situations where I have been successful the layour and structure is almost always initiated by others.

I would appreciate any tips others may have in actually helping me fix these problems.

posted by gadha to writing & language (15 comments total)

CS researcher here.

Some tips:

- Think of the reader. Have a particular person in mind - someone in a related research group. As I understand it, your work should be readable to an interested and trained expert, not necessarily in your field. Think about what you'd have to explain to get it across to them, not to a novice or a specialist.

- Read it aloud. It really helps to work out what sentences need filling out and what don't - you are (obviously) not going for a conversational style, but if it is hard for you to read aloud it will be hard for others to read full stop.

I always find it easier to cut things down than to build them up - maybe you could try writing something you know to be overly verbose and detailed, and then try to get it in the word limit.

Assuming you're at a university, do they have a skills centre or a staff development unit? These often have writing courses, which may or may not help.
posted by handee at 7:45 AM on January 25, 2007

If you're in school still go to your school bookstore and look in the IT majors section. They will have technical writing books there that are superbly tailored to what you should need.

I'll look later when I get home, I've still got mine by my computer. It was an excellent reference.
posted by PetiePal at 8:27 AM on January 25, 2007

You may find this essay useful. It's aimed at recent Cambridge graduate mathematicians writing a first paper, but section 4 onwards is good advice for any technical topic, and the whole is quite engagingly written.
posted by crocomancer at 8:51 AM on January 25, 2007

I would stop trying to be interesting with your papers. Write everything as if you were writing to a 4th grader and needed to be very, very clear. If you've communicated what you need to, then you've done your job. Revise everything to be simpler, to say more with less.
posted by xammerboy at 8:53 AM on January 25, 2007

Check out Michael Alley's excellent book The Craft of Scientific Writing. You can find it using Google Books if you want to see a preview.

It's an excellent manual, but it's also well written and engaging, so it's a pretty enjoyable read by the standards of such books.
posted by dseaton at 9:21 AM on January 25, 2007

I've found that having coauthors makes a big difference. Do any of your fellow researchers have similar or complementary interests? If so, collaborating on the design and execution of the work as well as the write-up can be an effective solution.

Having a second (or third or fourth) author enables you to focus on your strengths, bring in other viewpoints, and (often) produce better work. In my own research, I have been much more satisfied with the papers I've coauthored than those I've written by myself.
posted by i love cheese at 9:45 AM on January 25, 2007

Another CSE grad. student/researcher here. A few things:

*To be clear, when you say paper writing I assume you mean for submission to a conference or journal... yes? (just out of curiosity, which one by the way?)

*If the above is true I disagree with the whole, "write to a 4th grader" bit above. You are writing to fellow members of your research community, have them in mind as you write the paper.

*In my experience CS papers should be about what you did at a high systems or algorithmic level NOT about how you did it at a language / implementation level. (No one wants to know about your class heirarchy unless for some reason it is _essential_ to understanding your result.)

*Start out and work in. Think of your paper as a program and on some level design it as such. Think about the big picture- what did you do, what do you want people to take away. Divide that "story" into sections and recur into each one.

*I often find it helpful to start with the abstract becuase it helps you get a sense of that you want people to walk away with. It can always be rewritten later as your paper evolves

*It is cliche' but true. Tell people what you are going to tell them, tell them, then tell them what you told them. And do it on every level. The paper has ab abstract, intro and conclusion. Your major sections should have an intro and concluding paragraph etc.

*With regard to honing in on problem and solution try thinking about analysis and context. Not only how did your system work but why? Why do we care that it worked at all? These are important aspects of any piece of research if you want it to have relavence to others.

*Finally, and perhaps most importantly READ OTHER PAPERS. Get a sense for the prevailiing style in your community. The best way to learn to write is to read.
posted by lucasks at 10:04 AM on January 25, 2007

i_love_cheese: I agree with you that co-authors not only reduce the workload but make for much more diverse/stronger papers. Unfortunately in my current work there is nobody working on what I'm doing and ehnce I'm going it alone.

lucasks: Yes submission, I'm in systems so most systems conferences are my goal. I find that your comments are relevant and are exactly what I'm doing/have done. But at the end of the day I think my terse writing makes for much shorter papers. I find it extremely difficult to fit 12-14 pages with one piece of work and hence end up putting in more leading to classic comments such as "diffuse work, should split into two papers" or "has one title, two sets of work here". I mean there's only so much I can write about why I made the decisions I did, the testbed, the tests, etc... -- and when i try and overlook that I find my papers get too long-winded and stretched out.
posted by gadha at 10:31 AM on January 25, 2007

Another thing to think about is that you're trying to tell a story, in that your paper should, in a sense, have a narrative thread. (I presume there's not too much difference between papers in CS and papers in mathematics, which is what I'm familiar with.) Not that you're making things up, but there should be a flow. Outlining might help.

I would strongly encourage you to err on the side of saying/explaining too much; it's lots easier to cut than it is to put in. And nobody likes reading papers where the author says something like "this is obvious" and it takes a week of hard work to figure out why the "this" is true.

As others have said but bears repeating: write as though you are explaining what you are doing to a reasonably knowledgeable colleague---because this is in fact what you are trying to do. In terms of terseness, when you write something, have a little voice in your head that asks "how do I know this is true?" and then either you explain with a proof, with some discussion, or with a citation (unless it truly is something everyone will know). If the little voice doesn't work, then find a colleague. After a while, you will end up developing the little voice.

When you say "throwing away 3 or 4 copies", do you mean literally starting writing from scratch with a blank page? Or do you mean radically revising---e.g., using big chunks of what you wrote previously but changing the structure a lot? If it's the latter, that's not so horrible.
posted by leahwrenn at 10:43 AM on January 25, 2007

leahwrenn: I mean trashing the whole thing and starting from zero.
posted by gadha at 10:50 AM on January 25, 2007

A few tips off the top of my head, although my expertise is in tutorial writing:

1. Know your audience. Don't ever write to 4th graders unless you're writing for a 4th-grade audience. If you're writing for grad students or professors, don't be afraid of jargon.

2. Read. A lot. Find examples of writing you like, and read them over and over, so you stop focusing on the technical content and start noticing the words, formatting, and other writing aspects.

3. Write. A lot. Don't save your writing for an assigned paper here and there - practice more. Spend time in online forums or get a blog, and do lots of writing there.

4. Get some honest feedback. This is harder than it sounds - people like professors or fellow researchers are going to focus on the technical aspects and ignore the writing, and other random people might be turned off by the technical stuff. Find some writers you can send drafts to for feedback.

5. You mentioned terseness and sounding like a telegram. To me this sounds like one of two things: Either your grammar is bad like a telegram's (ATTACH PRINTER CABLE STOP INSTALL DRIVER STOP SELECT PRINT FROM MENU STOP) or you're just getting to the technical point quickly. The latter is a good thing, but you may be neglecting the human side - why does this work the way it does? Why should your reader care? What benefits can the reader get from understanding it? Ask yourself questions like this constantly as you write, and answer them in the text. Answer them tersely, though - nobody wants to read a 5-paragraph anecdote before you get down to the details.

6. Making your work interesting to the reader: this relates to those same questions. Imagine a reader standing over your shoulder and saying "Why should I care about this?" - answer them. If all else fails, start a sentence with "This is interesting because" or "This is important because" or "This matters because". If you can't think of an ending to that sentence, maybe you're writing about something that isn't interesting to YOU, which leads to...

7. Write about things you're passionate about. I realize you don't always get to choose a subject, but when you do, find something very interesting or significant to you and write about that. When you're writing passionately you'll find that it's much easier to make the writing interesting.

8. Look up Kathy Sierra's site, "Creating Passionate Users," and go through the archives. She's written tons about how to make technical writing interesting.

Good luck!
posted by mmoncur at 11:04 AM on January 25, 2007

One more thing: If you don't have co-authors, find another grad. student to read it and not just tell you what is good and bad, but to make concrete suggestions. You can always ignore them and it starts to give you a feel for how ideas might be presented/ spun. If you don't have someone around who will do that you can email me (email's in profile) and I would be wiling to take a look and offer suggestions. (Don't worry - I won't swipe your research...I'm not a Systems guy, I work on Microarchitectures for Quantum Computers.)
posted by lucasks at 11:32 AM on January 25, 2007

some small examples of your text would be very helpful.
posted by fake at 12:04 PM on January 25, 2007

Systems-oriented CS researcher here. I read your question with some interest, as I have had similar struggles. Some techniques that have helped me:

- While you may be working alone, your work is not isolated from the field. It is important to explain how your work fits into the bigger picture. What problem are you solving that has previously been unsolved, and why is it an interesting thing to do? It is surprising how often I review conference submissions that are vague on this or ignore it all together.

- Keep that big picture for your work in your head as you develop your paper. Describe each component in your system, but be careful to explain how it fits into the bigger framework -- both goals of the system, and contributions to the field.

- Read the papers coming out the top conferences. Go into the archives for SOSP, OSDI, CCS, etc. and read everything you can. Read them because as a researcher in the field you should know that stuff, but also read them with an eye toward style: these are what good papers look like.
posted by event at 3:34 PM on January 25, 2007

"I find it extremely difficult to fit 12-14 pages with one piece of work..."

Are you saying that you feel the need to fill those pages? I usually have the exact opposite problem (CSE grad student also) and squeeze things down, for conference papers anyway. But why do you need to fill the page limit? As a reader or reviewer of papers, I'm more than happy to come across a shorter paper. As long as you have good content and enough in there to support it well, I don't care if the paper doesn't reach the page limit.

Or, if you think the shortness really is a problem, then definitely check out other papers. Do they cover just one idea? Are they long-winded? If not, what have they included in their 12-14 pages to support their idea that maybe you have not? More results? Longer description of the testbed? More background or related work? Heck, maybe even larger figures?

Terseness: Is it a content issue or a style issue? That is, do you not write enough for the reader to fully understand, or are your sentences just joyless or painful to read? If it's the former, then definitely get someone else to help you. Another grad student, your advisor, some other prof. Ask them to read it, then have a conversation about the ideas. Have them tell you what they don't understand, and check their understanding vs yours. That will help you figure out what more to include.

If it's a style issue, then I think you just want general help with writing. There are books, of course, and your university might have classes (either for-credit or workshops in a writing center somewhere?) with writing help.

As for flow, I agree with the "tell a story" sort of advice. Plan it out in advance. Figure out what information you want to convey. Figure out in what order it should be conveyed. Figure out what supporting information you will need to include. Plot it all out in advance. Make this organization clear to the reader in the outline. Either explicitly, "In Section 2 we discuss [blah]. Section 3 contains [blah]. Etc.," or implicitly by making your introduction a compact version of the entire paper. Or both.

Then, I think that transitions are one key to having a good flow. It is jarring for the end of one section to slam right into the beginning of the next when the two sections cover different aspects. If one paragraph describes the last portion of your algorithm and the next is suddenly describing your experimental results, the reader can be thrown off. So at the very least, ease into each section with an introduction of what is coming up in that section. Even better, relate it to the previous section. Always try to tie things together.

For example, let's say Section X.1 described the first phase of some algorithm, and Section X.2 is about the second phase. Either of these could be the start of Section X.2.

"The second phase of our algorithm performs a branch and bound search to find the largest set of mutually compatible elements, given a set of candidate elements and a compatibility relation encoded as a BDD."

"Once the first phase of our algorithm has produced a set of candidate elements, the goal of the second phase is to compute the largest pairwise compatible subset of those candidates. As we described earlier, the criteria for compatibility are provided explicitly in. . ."

I don't claim to be an awesome writer, but hopefully those examples give you an idea of what I'm talking about. (And if it's really not clear, well, I think the second version is better.)

Oh, and to amend event's point: Read those papers with a critical eye for style. Plenty of poorly-written papers are accepted to top conferences, and if you come across one, you can learn what not to do from it.
posted by whatnotever at 3:52 PM on January 25, 2007