We write to explain what we have done, how we have done it, what we found, and why it matters.  (Alternatively, you can rephrase all these things in a future tense when you are proposing to do research.) 

Common mistakes that I see people make are:

  • Failing to provide a logical structure in their writing.  Without a logical structure, the reader (and often, the writer) will quickly get lost and confused.
  • Failing to arrive quickly at the point. People don't like to waste their time.  You need to convince that you have something to interesting to say.
  • Failing to express the key ideas early. See the previous point.  What is your key message?  Say it!
  • Failing to recognize who the audience is.  If the audience is your scientific community, they don't need to know the history of the world.  They need to know the subject matter that you will be writing about.
  • Failing to recognize that people have short attention spans. The reader is unlikely to read your entire paper.  You want to provide enough structure for them to find what they are interested in.  You want them to leave with the impression of good work, even if they don't come back to it until later.
  • Failing to recognize that it is necessary to remind even experts about the basics. Experts are busy and distracted.  A short and gentle signal to remind them about what this area involves can make all the difference. Furthermore, they need to see that you have a clue about what you are writing. 

Key conceptual elements

There are key things that a paper will generally have to talk about:

  1. the problem;
  2. that the related work does not address the problem or not well enough;
  3. your proposed solution;
  4. an evaluation that your solution improves on the problem beyond the related work. 
  5. the results.

There are exceptions of course, but without all these elements, expect to have problems convincing reviewers/committee members.

Note also the difference between (1) an idea/a model as the proposed solution, and (2) a tool.  In general, the tool is a reification of the idea, a "making it real".  Often in software engineering, an idea by itself won't be enough: people have ideas all the time that fail to work.  A tool is needed as a scientific apparatus that will support empirical evaluation.

The title

The title is the simplest signal to the community as to the point of the paper, who should read it.  Don't waste the opportunity.

A horrible title provides the name of some software tool.  "The Fubar Tool": wow, this says nothing.  Why would I want to read your paper?

Often, we see titles that refer to the solution.  These are so-so.  Better are titles that refer to the problem.  Titles that grab the attention are good, as long as the reader can get a hint at what the point is.  Cutesy but unhelpful will annoy.

Go back and revisit the title after you have written the body.  Be prepared to change the title.

Abstract

This is a summary of the key conceptual elements.  Write this late in the process.  Succinct.  People will often not read past the abstract, so you want them to have received the main points!  Note also that the abstract is not part of the main paper: people may skip the abstract and start reading the introduction!  This is why it is OK to repeat some of the points, even verbatim, between the abstract and elsewhere.

Note that, traditionally, the abstract was a summary added by an editor, which is why it would be written referring to the authors in the third person.

1. Introduction

When I read a paper, I look at the title and the authors.  I read the abstract.  If it sounds interesting but I have doubts about the point, I will start to read the introduction.  If it seems interesting, I may read all the introduction and jump to the conclusion.  Only rarely do I read the remainder of the paper, only in cases where it is of deep interest to me: for example, if I am looking for work to build atop, or I am looking for related work and I need to understand the differences with what I will do or have done.

I see poor introductions all the time.  Ones that make me groan.  Ones that I stop reading unless I am forced to proceed because I am reviewing the work.

What can you do to avoid this antipattern?  Structure.  Structure!  STRUCTURE!!!  Go back and review my introductory points about common mistakes.  Review my earlier points about not reading even the whole introduction. You need to picture the reader and their thoughts as they proceed through the introduction in particular.

Here is a standard structure that I often use.  It does not fit all situations, but it is a helpful model.  Be wary if you deviate from it.

The following is described in terms of paragraphs:

  1. What is the context? What is the problem? The difficulty in writing this paragraph is that it needs to be fairly short and yet it could be the only chance you have to convince the reader. There are likely to be about 5 sentences.  The last one has to express the problem in a way that gets the reader to keep reading, a "cliffhanger".  At the end of this paragraph, the reader should think, "Hmmm, I see the problem, somewhat, and it sounds interesting but it is not so clear to me".  [The "not so clear" isn't a requirement, it is a bit of wiggle room for you.]
  2. Expand on the problem with an example.  This is not always appropriate, so this is optional.  It needs to be short.  It can be expanded upon after the introduction.  At the end of this, the reader should think, "OK, I get it"; they might also think, "Hasn't this been done?" or "I am not convinced this is a real problem."  That's OK.
  3. A short overview of the related work.  This is simply a signal that you are not clueless.  You are aware of the related work and you see problems with it: it addresses different problems or it fails to meet the needs.  Don't mention particular papers, but give citation lists; details come later.  "I'm not convinced that this is original, but they seem to know what they are talking about."
  4. Your solution.  How does it address the problem?  It is only one paragraph, so the reader won't get more than a clue about the point, but that clue is important.
  5. Evaluation.  Your solution may not actually address the problem.  The competition may be better.  Give us an idea of how you pushed against your work.
  6. Overview of the paper structure.  Don't mention the introduction.  Don't mention the conclusion (although I have reviewed papers occasionally without conclusions, it is a huge mistake in my opinion).  Otherwise, tell the reader what to expect from each remaining section.
  7. The novel contributions in a sentence or two.  Your paper doesn't provide a dozen novel contributions.  Get real.  But it should provide one.  Maybe two or three in unusual cases.  Avoiding trying to inflate these; it makes you look dishonest and/or clueless.  The contribution is probably the solution aimed at the problem.

In general, it is good to have the introduction finish on the first page.  This is not always doable, but avoid making it go on for more than a page in total.

[Forward Referencing]

With the exception of the paragraph overviewing the paper structure (and similar overviews in later sections), it is generally a bad idea to refer to material later in the paper that the reader has not yet encountered.  It forces them to jump ahead to see the point.  This is disorienting and you can expect reviewers to complain.

2. Motivation

This is a more detailed example.  It is not always appropriate but chances are that the reader did not understand the problem so well in the introduction.  You can introduce the solution (as a screenshot) to suggest where you are going, or you can leave the developer with some difficulties that you will address.  I've used both approaches in different situations.

3. Related Work

Sometimes, I put the related work next, to get it out of the way.  This is typically where the readers are liable to think that the problem has already been solved.  Otherwise, I put the related work towards the end, either before the discussion or after the discussion.  In particular, if I want to compare the related work to my solution, I need to have talked about my solution first.

4. Approach

This is the real meat of the paper.  Sometimes it makes sense to divide it into multiple sections if the solution is particularly complex or has logically distinct parts.

5. Evaluation

What were your research questions?  [Sometimes, one research question is sufficient.]  Make sure that your evaluation actually addresses all your research questions.  That is, there will certainly be additional questions to address, but this is not the place to talk about them.

How did you design your study?  If you used human subjects, how did you recruit them, who were they (class, not names), how many, what experience, etc.?  Your results may have been biased by how you did this, so give us some details.

If you used existing software systems, which and how did you select them?  Why these ones?

What are the different treatments?  Was there training performed?  What steps did you take to avoid bias?

Unfortunately, there are too many options that are applicable to different situations to give more than this brief overview here.

The one piece of advice I will give you: make sure that there is the possibility for your study to have failed.  I have seen too many times studies in which the authors measured something that was already implied by how they set up their study.  This is called circular reasoning.  It causes a lot of wasted time and rejected papers.

6. Discussion

There are generally lots of additional things to discuss. 

"Threats to validity" is one that is almost always pertinent. There are about 4 kinds of validity to worry about, although it depends on how you want to count them. 

"Internal validity" is whether the results you see are due only to your solution and not some external factor.  For example, if you wanted to show that your novel approach was better than an existing approach, it would not be a good idea to have toddlers use the existing approach and experts with decades of experience use your approach: this would lack internal validity.

"External validity" has to do with whether your results will apply to other situations.  Sometimes, "generalizability" is separated from it, meaning generalizability to other subjects or other tasks; in which case, external validity refers more narrowly to whether different results could be expected if different researchers conducted the study.  In practice, worry about biases in your study design and methodology.

"Construct validity" has to do with whether your measurements mean what you want them to mean.  For example, using shoe size as a proxy for intelligence would have questionable construct validity.

In addition, you can discuss why you made certain choices and what other options exist.  You can discuss future work.  You can discuss implications.

7. Conclusion

The reader may not have read the body of your paper.  Revisit the key points (see above).  You can be briefer about the problem and solution now.  Focus on the results and the implications.  This is your last chance to leave the reader with a good impression of you ... don't throw it away!

Acknowledgments

Funding.  Appreciation for help from a colleague or good reviews.  With page limits, there isn't always space, but it is polite to do this.

References

Once upon a time, I thought the references were a silly waste of space.  Then I learned to be a scientist and scholar.

Bad papers are completely sloppy about referring to the work of others.  References acknowledge the "shoulders of giants" that you stand upon [most famously, said by Newton, though not original to him], but also contextualize your work.  The actual references in here need to be findable by the reader.  It drives me crazy as an editor when the references are a mess.  Did you actually read those references or are you just pretending?

Furthermore, we have a habit of making small claims in our papers that could use some back up from evidence.  People often cite other people who have said the same thing, who cite others who said the same thing, who cite others ....  Where's the actual evidence?!?  Ah, such a house of cards. 

But that is a story for another day.