Guidelines for writing papers and reports

It is very important to pay much attention to the quality of your writing. Most readers react to style, clarity, conciseness first; even before trying to understand what you're writing at all. And indeed, this is something quite natural. Here is some piece of advice on how to write your papers and reports in such a way that you will actually get readers...

Organization

• Your writings must be well structured, semantically speaking. This means things will probably not go in chronological order. Rather, try to imagine what would be the expectations of a newbie reader: what's the global direction / purpose of the work, what are the different steps to undertake etc etc. This always implies the following structure:
  • An introduction with the general context of your work, a description of the problems you want to address and how you will address them. Finish the introduction by announcing the plan of your document.
  • As many chapters as needed to articulate your presentation, usually with bibliographic matters first. If you have independant parts in your document, it is acceptable to spread bibliographic contents in the different chapters they belong to.
  • A conclusion that clearly summarizes the contents of your writing, in the same order as the presented material was detailed. The conclusion should then emphasize on the main interest / features of the material you have presented, and end up by widening the debate: which issues still have to be worked on, which new questions or problems arise, which other topics appear to be related etc.

• Always go from the general to the detailed. Don't fear to be redundant from time to time. This does not mean putting things differently in the same paragraph; that would be useless. But sometimes, it is nice to be reminded of something that was seen in a previous chapter, when it is necessary to understand what is coming next.

• Always make the structure and the logic of your document very clear. There should always be a logical reason for going from one section to the next. If there is not any, then something is wrong in your reasoning. Most of your structural articulations should also be explicit. For example, it is very comfortable for the reader to have a short paragraph at the beginning of every chapter saying something like "In the previous chapter, we have seen this and that. This raises the question of so and so, which is the purpose of this chapter.". In other words, do not let the user guess your structuring. Tell him explicitely what it is.

• Always make it very clear what is your work, and what is bibliography. This will help the reader figure out the interest of the material he is reading: where is the novelty, what is the current state of the art.

• Always include a substantial bibliography, even for things you find obvious. Nothing is obvious for everybody, and it is better to have too many references than too few.

• If the document is long, don't be afraid of including an index, as indexes usually make the difference between a book you read once, and a book you can read several times.

• Always make your prerequisites very clear, and very early: if some knowledge is required prior to reading your document, say so, and provide references. Again, this stands even for things you may find obvious. If you suppose the reader has a basic knowledge of OCaml's syntax, just don't assume it. Say so.

• Write the introduction and the conclusion last. Write the abstract only when all the rest is written. The abstract should come rather easily when the document is written, apart from the fact that you must summarize a whole chapter in only onle sentence, of course :-).

Style

• Don't be afraid of slicing your writings. Chapters, sections, subsections and paragraphs are necessary; don't fear having a lot of them. If you end up with 3 pages of text with no apparent sectionning, then something is probably wrong / missing in your structuring.

• Having many levels of sectionning does not mean you have to number all of them! 4 numbered levels are probably already too much. Remember that you have a \paragraph command in LaTeX.

• Don't include full listings in your document. This is meaningless: at a given step, only a small part of the code is related to the point you are trying to make. If you want to include full listings, put them in the appendix. Use only commented excerpts in the document's body.

Language

• Stay concise: write short sentences and use logical constructions. Do not try to be too literary; you are writing scientific material. A four lines sentence is too long. It should be splitted.

• For english writing, the traditional dialect is american english. Please stay consistent in your document, do not switch from one to the other. Here are some american english specificities:
  • you write honor, not honour;
  • you write specialization, not specialisation;
  • ...

• For english writing, pay attention to false friends and idiomatic constructs. If you are trying to be (too) literary by imitating a nice french style, you are basically wrong. They never translate as you think they do. Let us take a very good example from one of the 2003's reports (exercise: guess which one): "Among other things, were developed improvements relative to typing". This sentence is triply wrong: first, the coma is useless because you have no logical entity to separate from the rest. Second, this is a word for word translation of a french sentence, but it does not work in english: only in very rare occasions you are allowed to put the subject after the verb. I know it sounds nice in french, but it simply does not work in english. Finally, the word "relative" is not a very good choice (though still correct). "related" is a better choice in english (relative also means a member of the family). Read more about CommonEnglishMistakes.

• Please, please, please, use at least a spell checker, and re-read your document at least 3 times before submitting it to other people. You should let pass some time between your subsequent re-readings because one has a tendancy to miss obvious mistakes when they are still "hot". It is incredibly difficult and painful to have to read badly written material, but when it comes to obvious spelling mistakes, it turns out to be just impossible. One cannot concentrate both on the meaning and on decryption.

• When in the final re-reading phase, do not concentrate on the contents. It is too late for that. Do not try to understand what you have written. Pay attention to the grammar and the spelling. Most mistakes that go unnoticed are due to the fact that people do not realize there are different ways of reading a document.

-- DidierVerna - 29 Jan 2003

PresentationGuideLines

• WritingPapersAndReports: Global issues when writing a technical text
• CommonEnglishMistakes: *Learn to avoid them, learn avoiding them
• HowtoWriteEnglish: This text shows you what you must not do when attempting to write in English
• OralGuideLines: How to make a nice scientific presentation

to top