How to write a good (enough) report
-Andy Ruina, ruina@cornell.edu
(Created 8/2/2000 and modified 53  times, most recently on 1/16/2024)

What is good writing? It is text that convinces somebody of something.
How do you do it? You form your idea, write it badly, and then revise again and again, trying to be more and more clear.
What's the key?  Don't fuss over 'writing well'. Instead, try to get your message across.

I. Why this essay?

I want my students to write reports that I will like reading.   I hope this essay helps them do that. And maybe it could help other students too.  There are two main questions:

        1) What is a good report? and 
        2) How do you write a good report?

By 'good' I only mean 'good enough' or 'not too bad'. That's all I can do; a good writer can  edit what I write and make it smoother, shorter and more clear. So, not too bad is all I can do and all that I can hope for from my students.  By 'how?' I  mean what should one do and think to improve a report that is not yet good enough to make it good enough.

Who am I to give writing advice?  I have dyslexia, bad hand-writing, bad spelling, a small vocabulary and I don't know what a past participle is (or was). I got bad grades for writing from first grade through college. And, there are already thousands books and web pages about writing by good writers.

Yet, over the last few decades, after people stopped trying to teach me how to write, I have written a lot, read lots of student reports, and learned a little about writing.  The expert advice on writing, in the books and web pages by experts,  is mostly about more advanced things, more subtle or refined things, than the basic things that I understand and care about here.

The main thing I have learned and would like to convey is in the few sentences under the title above.  Repeating,

What is good writing? It is text that convinces somebody of something.
How do you do it? You form your idea, write it badly, and then revise again and again, trying to be more and more clear.
What's the key?  Don't fuss over 'writing well'. Instead, try to get your message across.

If someone could have got this basic message through the thick skull of the younger me, I would have had a better writing life, and thus, maybe,  a better life generally. By spreading the message above over the many paragraphs below, maybe some of the ideas will seep into some peoples' heads better than they seeped into the head of the younger me.  Maybe  into your head. I am trying to help you get something into your head earlier in your life than  it got in to mine.  If so, then I think that you will write better, please the people around them more, and be happier.

This is only about non-artistic practical writing; it's not about writing Haiku or songs.

Check list.  Sections III ("Sixteen things that lots of students don't get") and IV.A  ("Organization") make up a check list. These are the key things, or features, your paper should have, and should not have, by the time you call it done.

II. What is a good report?

A. A report is not abstract art, it's a message

I used to think that good hand-writing was ornate and flowery and beautiful to an artist's eye. But, I could never make my messy scrawls smooth like that. Now, I think that the most important thing about hand-writing is that it be legible. Then, people can read it, which is the point. By printing slowly, I can write legibly. My blackboard work might look like it's written by an eight-year-old, but usually people can read it. I've gone through the same transition with my thoughts about writing. I used to think of writing as an alien thing unto itself, a kind of art to be judged by its own arty value system. So, I thought that good writing used fancy words in fancy ways with metaphors, alliteration and all that. Something I can't do. Now I think that the most important thing about writing is that it be understandable. And, using simple words that I understand, I can write things that are undestandable! At least kind of. Now, I think of both hand writing and text writing as a means to an end, an end that is achievable. Namely,

the goal of writing is not an abstract notion of `good writing', but communication.

Conversely, now I know that a stream of beautiful big words, written with beautiful handwriting (or great computer formatting), and even with perfect spelling, clear topic sentences, perfect grammar and all that, can still be bad writing.

Lots of students seem to have the same misconception that I had about writing. They think that writing is some strange artistic thing to be judged  by a value system that they don't quite get. So, they have the same writing problems that I had; they try to please some abstract writing god they can't quite see out of the upper corner of their eye. Instead, they should just try to say something clearly to another person. If you are one of those confused people that think that writing is making beautiful art, then here is the key:

Don't think 'good writing is beautiful',  think  instead 'good writing is clear'.

As someone with a lifelong alienation from the humanities, discovering this functional aspect of writing is liberating. It turns writing from a foreign artistic task that I used to rebel against, into more of puzzle or an engineering problem: an essay is like a computer program. The reader is like a computer; and the reader's new outlook is like the computer output. So, writing is like programming ...  and debugging. That functional view of writing makes it more straightforward and, for me, more approachable.

Actually,  just shifting the goal, from style to communication, is almost enough to make good writing, or at least good-enough writing. Even if you have weak language skills, once you make your goal saying something, rather than trying to show that you are skilled at language, you can, if you try and revise, write tolerably.

B. Write to change what is in someone else's head

Your goal is to change (to alter) your readers' minds. Then, maybe,  you can change their actions. After they have read your stuff, people should know more, and maybe they should think, feel or act differently in a way that will please you, or them, or both.

Some writing guides say, "Writing is communicating to an audience for a purpose." They mean that, when you write, you should keep your reader and intent in mind. This approach comes naturally if you are pleading to get a boyfriend or girlfriend back, asking your parents for money, questioning the registrar about a bill, or complaining to a teacher about a grading policy. In those contexts you know who you are writing to and what you want. But when, instead, the explicit goal is to satisfy a teacher's demand that you write a paper, it is not so easy to focus on audience and message. So, even the first step, figuring out who you are writing to and how you want to change their thoughts, is a special challenge in school-like situations.

Here is a possible approach for school writing. As a student writing about your research you want your advisor, future students and possibly readers of a technical journal to learn things from you. You want these people to be more successful when they try to pick up where you left off. Your writing should tell your readers what question you are asking, should make them interested in it, and should make them understand and believe your answer. If you succeed, they will not only learn something and enjoy being engaged, but they will also think better of you and, by association, the people around you. Your readers are probably already interested in your general problem, so your main goal is to teach them as much as possible about it. If their work depends on yours, it will go better because they have learned from your report.

Warning. Don't just write for a specific audience, and only that audience. When writing for Professor Smith, keep in mind other people like Professor Smith. That is, don't make reference to, or make your message depend on, things that only you and Professor Smith both know, and that you both know that you both know. For example, don't write "... on the lab scope ... in class ...". Instead write "... on the lab oscilloscope (HP model 3468B)...in ENGRD 2030 Dynamics lecture on Feb  1, 2021 ...". Even Professor Smith will understand better that way.

C. How? Trial and error

The basic method is trial and error. That is, to write well you repeatedly create, test and reject. This is how biological evolution works; survival of the fittest. This is the essence of the scientific method, of problem solving, of design, of computer programming, and most things that involve discovery or creation. The only sure way to make good things, including good writing, is to make things (some good and many bad) and keep the good parts and throw out the bad.  You  repeatedly create, test and reject. If you are willing to try out new things, check if they work, and are willing to toss them  out if they don't work, then you can learn, discover, design ... and write. How? You  first write something that might be good but is much more likely bad. Then, you rearrange words, phrases, sentences and paragraphs. Are the new groups of words an improvement (that is, do they better get your message across)? If so, keep them. If not, change them or throw them out. Do this many times,  and you will have something that is good, or at least good enough.

Isn't there a better way? Here is one unrealistic fantasy.  You wake up in the middle of an inspired dream and write down what the voice is telling you. Here is another. You follow the directions in The Handbook of Intelligent Design.  Unfortunately, back here, back in the real non-fantasy world, those inspired dreams are rare. And that handbook of intellgent design doesn't exist.  Fortunately, here is a funny thing. If you get really involved in trying to figure out what you are trying to say, and to whom, and trying to say it better and better, you sometimes do, eventually, get inspired. After hours or days of grueling trial and error those rare inspired moments sometimes do come. And,  if there is a secret of "intelligent design", it is probably just this: apply common sense trial and error again and again. Isn't there a better way? Usually not, not unless you are the Beethoven of writing.

In summary, so far, first think about what you are trying to say and to whom. Next, try to say it. Then, keep improving what you have so far by a process of trial and error.

III. Sixteen things that lots of students don't get

Student reports too-often provoke some common reactions from me. Here are some.

A) Aim for content not style. Often students, instead of trying to say something, they try to mimic some high-school-essay style. Why? Because they have almost no practice at communicating for a purpose. As a student it is hard to sincerely engage in an artificial task like "Write an essay to convince X of Y". For example I was once asked to pretend to write to my grandmother to convince her of the benefits of coed dorms. I couldn't pretend to care about that. So I wrote about my guess about the teacher's concept of  X (my grandmother) and tried to convince that fictional person (my imaginings of my teacher) what I thought that he thought about Y (coed dorms). So I tried to write in a style I thought my teacher would like, as if that was an end in itself.  I feel like many students write to impress a poor-fidelity model of thier teacher. Or they might try to "communicate to an audience for a purpose" in this indirect way: they try to let their teacher know that they have a poetic and creative nature so deserve a good grade. Too many students  pursue these perversions of the real goals of writing. Or,  they might not have rebelled against the school writing game, the game in which they were to pretend to have a goal that they didn't really have. So they never even tried. For some mixture of these reasons, in school  many students get almost no practice of writing for a reasonable purpose. And, away from school, many students also have little experience of writing for a purpose. So, when forced to write, they forget about communication and resort to chasing, with more or less sensitivity,  their teachers' tastes, a style they hope will give a good grade.  Most often the result is writing that is of no use and no fun. (And might sometimes get a good grade because the teachers are also playing a game of pretending to be someone who they are not.)

Communication, not style, should be your main goal. Fancy wording that you think might please a junior-high writing teacher has a high chance of not communicating well. So, it is bad writing.

What should you do? Try to give a clear message, not one with good form. In the end the style might be OK  because, as the architects say, 'form follows function'. That is, if you make something function well, here that means creating text that communicates well, then good form, good style, might happen as a consequence. But,  if the form and style don't end up great, so what? It's the function, communication, that you are trying for.

B) An affected tone is bad. Don't pretend to be someone else, and write things that you think that person knows, and in their style. Write what you know in your style. Faking content, or trying to be funny, cute or grand, especially when that doesn't come naturally to you, will turn people off.

C) A bad first draft is O.K. Once you have some sense of what you want to say, you need to get it onto your computer. Your amorphous idea is like a lump of unformed clay you need to put on the table before you form it into pottery. Or, your collection of small ideas is like a pile of jigsaw pieces. You need to scatter them on a table before you start putting them together. So, you need to produce something, something that has in it, perhaps poorly formed or scattered, some of your ideas. It's ok if it's bad, because you are going to revise it. As Marc Raibert said, "Good writing is bad writing that was rewritten."  Don't let your anxiety about quality stop you from starting. You're going to fix it anyway.

D) Writing is work, mostly revising. Once you have a lump of clay on a table you then have to shape, reshape and finally glaze it. That reshaping and finishing takes most of the time. Same with writing. Once you have your ideas on paper in some form, you have to change and rearrange them, and that revising takes most of the time.

Puzzle pieces. Thinking of your writing fragments as puzzle pieces, you have to find the pieces that belong next to each other. You have to discover that you are putting together a different picture than you planned. You have to make new pieces that are needed for that new picture. You have to get rid of the pieces that you realize belong to some other puzzle. And you have to get rid of duplicate pieces.

Kill your darlings. Throwing away defective, irrelevant or duplicate pieces, pieces that you had carefully made (that is, text you carefully crafted, your "darlings"), is really hard. Nonetheless, you should kill your darlings.  This is not as bad as it seems. When you delete, say,  a paragraph, you are not throwing away all you learned while writing it. You are getting rid of something distracting or  clearing space for something better. So, the writing and tossing is not really lost time.  It's just part of the process.

99%. When I was in 8th grade my next door neighbor was Bernard Malamud, a successful writer. His wise words to me, the kid getting Cs and Ds in English, were "They say writing is 5% inspiration and 95% perspiration, but really its more like 1% and 99%." I thought he was overstating this to make a point. Like I have thought at times about "if there's a will there's a way" or "it's not what you know but who you know" or "the university is more interested in research money than in education" etc. But it turns out that `writing is mostly sweat' is one of those exaggerated sounding sayings which, despite our wanting to dismiss it as over-statement,  is basically true. I didn't get it then. So maybe you won't get it now. But it's true. So the sooner you accept it the better. Writing is more revision than creation, more perspiration than inspiration,

E) Writing takes time. If you are talented and your paper is not for journal publication then maybe you can do with 5 revisions or so. But good papers often go through much more revision than that.  And that takes time. I can type 50 words per minute. But, on average I can write and edit about one word per minute. One. For me writing is 50 times slower than typing. The work of making something clear is about 50 times slower than typing it out. This is backwards from what I used to think about writing. I used to think that writing was hard because my pen and keyboard were too slow to keep up with my thoughts. Actually it's the opposite, my thinking can't keep up with my typing, not by a long shot. OK, I am older and maybe I think slower. But I don't think that's it. I think that what I used to think of as ideas that I couldn't write fast enough were probably chaotic thought fragments, topics but not coherent ideas. I was wrong to think that the slow part was, effectively, dictating to myself. The slow parts of writing are the formulation of the ideas in your head, and then refining, again and again, what you have already written down.

50:1. To finish a good paper everyone, even someone who got A grades for writing all through school, needs to do lots of revising. For Malamud, for me, and probably for you, good writing comes from editing and revising. Especially rearranging words, phrases, sentences, paragraphs and sections for clarity. Then, as the writing gets better in superficial ways, you will better see that you need to change deeper things, and add new ideas. These changes will cause a new need for fixes, for spelling checks, and so on. This way, 50 words per minute of typing leads to 1 word per minute of acceptable writing.

Slow is fast. This slowness of writing may seem depressing. But it isn't. Why? Because, even if you, like me, have little talent, it means that if you put in the time you will eventually revise your initial mess into something that is good enough. And, on the plus side, slow isn't really slow. If you polish a word a minute for 40 hours a week, for 50 weeks a year, and for 50 years, you will write 6 million polished words in your life time, about 20,000 book pages, about 7 times what Shakespeare wrote.  That is, one word per minute is actually wildly prolifically fast! You have to be 7 times slower than a word per minute  to keep back with Shakespeare.

F) Writing is a sport. The time might pass better if you think of writing as a game. The goal is to get your reader to understand and believe you. Each small change in your text is like a move in the game. Think of a reader as a customer and that you want to sell them some knowledge. Or, think of your readers as lost sheep, wandering off unaware of where they should go. You must herd them in, reasoning from basic common broad ideas (a big field) to the central line of your argument (the gate you want them to go through). Whether you think of it as a game, a sale, or herding, the sport is trying to funnel your reader from the infinite world of alternative ideas into your intended line of thought.

G) Good writing is usually friendly. Tough or stern language often pokes people into fighting back. Even if you think your logic is air tight, or if your message is really a command, if you write with a pedantic, condescending or demanding tone it may make your reader rebel, stop paying attention and to miss your great explanation. For example, if you read between the lines, this essay is  a warning (to my students): "Do you want to get a good grade from me? Then follow the advice here!" Nonetheless, with the exception of the previous three sentences, I have tried to write it with a friendly tone.

H) Get inside your reader's head. What do they know and what don't they know? When reviewing things they already know, you should do it clearly and concisely. That way you build trust. Then move on. When teaching your readers something new, you can't base it on other things they don't know yet. You can't assume they know what you are trying to say, or how it contrasts with other things you are not saying. Often students seem to be thinking "You know what I mean, Professor Smith" in between sentences. Instead, imagine Professor Smith's friend is reading, and after each sentence she is saying to herself  "I don't know what th f*ck you are talking about!". Then, write to prevent that.

I) Good writing is organized. There is a conflict between structure and flow. Your organization has to deal with that.

1) Text is one dimensional, ideas are not. There is an unresolvable conflict between the linear arrangement of words on a page and the multidimensional interconnected nature of human thought. Writing is one dimensional, ideas are not. Neither massively cross-linked hypertext nor concept maps,  are yet acceptable replacements for conventional linear text. So,  you cannot allude to every connection between ideas at every mention of one of the ideas. To avoid tangling your linear text you often have to postpone mention of key connections. You may write one phrase about one idea, the next about a second idea, and a third about the connection between the two. Even though, in your mind, the first two ideas are meaningless without the third.

2) Put similar ideas near each other. This applies within a sentence, from one sentence to the next, from one paragraph to the next, and from one section to the next. Although you may have written your first draft with an organization in mind, you will inevitably discover a new organization during revision. As you put similar ideas near each other,  sentences and paragraphs will condense and congeal into larger and larger sensible units. And redundancies, things you need to delete, will be revealed. To put your text into order you need to work both on the small scale and the large. You have to put related words, phrases and sentences near each other. And you also have to move whole paragraphs, and maybe whole sections, to keep related ideas as near to each other as possible.

3) Hierarchical structure. When you are done, a paper will have an implicit organized outline with a depth of 3 or 4 levels from sections to subsections to paragraphs to sentences. Each should have a purpose. For example, each paragraph should have a scope that you could express as a paragraph title. This paragraph title could end up being the first sentence, might end up being a low-level heading, or might be clear enough so as not to need explicit expression.

4) Logical flow. A given sentence either starts a new idea or explains more about the idea in the previous sentence. A sentence's role should be clear by the place of the sentence in the document (i.e., the lead sentence in a section), or by meaning (the sentence's content makes its role clear), or by wording (e.g., use of "furthermore", "however", "additionally"). Although structured, the paper should also flow as a logical linear stream.

J) Writing helps your thinking. It is hard to force your multidimensional ideas into a linear stream of words. But forcing ideas into an ordered sequence of words usually shows mistakes in your thinking.  That is, you usually have to edit your ideas too. Although you write to share ideas you already have, writing your ideas helps you to develop them. Extruding your wide-ranging thoughts into one thin line of ordered text forces a scrutiny of them that is hard to achieve any other way. It's not just writing that is hard work, thinking is also hard work. And systematic refinement of your writing forces you to think. Trying to write well about something is a tool that helps you understand your own thoughts. Most often, by trying to write clearly about an idea, you clarify the idea in your own mind.

K) Get someone to read what you wrote. You need sincere readers, not necessarily good editors, to see what gets across. When you try an engineering design you inevitably discover pieces that jam, circuits that overheat, and user abuse that you hadn't thought of. Most computer programs fail when first run. Similarly when someone reads your work, no matter what care you took in writing it, something won't get across to them. They will see ambiguities and paradoxes you hadn't imagined, and they will have questions that you obviously have to answer, but unfortunately didn't (yet).

Finding defects is good. Good readers of your early drafts will point out, or reveal by their misunderstandings, big problems. So it is easy to feel defeated. But that is the wrong reaction. The bigger the flaws discovered, the more your paper will be improved. The next reader will help you find more flaws, and even flaws in your first edits. And so on. Your readers help you with one of the key parts of the evolutionary process: finding errors. Finding errors is good because then you can fix them.

A bad first draft is good because that lowers the threshold for starting to write. But, don't give a bad first draft to your test readers. Even though you know multiple drafts are coming, you shouldn't give your test-readers something with many known flaws. That would be like testing a new machine that you know has missing pieces. When it doesn't work you don't learn much. The same with test-readers and writing. Known flaws will effectively hide the flaws you don't know about yet. The better the document you give to a test reader, the better she can find problems which you didn't find, the more your document can be improved from your reader's help.

L) Hiding the truth is lying. As a rule, you shouldn't lie and deceive. Omitting things to hide them is also deception, so it is generally a bad idea. Hiding by omission, conveniently not mentioning something a reader would want to know, will unfairly mislead some readers and anger others. On the flip side, being open about flaws, or about the limited scope of your work, can help build readers' confidence in you, and therefore in the results that you do want to present. So, for example, if you didn't accomplish a central goal, saying that prominently and clearly will help build your readers' trust.

M) Credit assignment must be clear. People whose main product is information, people like professors and graduate students, are sensitive about intellectual property. To them, your presenting their ideas or diagrams, or those of other students and researchers, without proper citation, is stealing (so says Peter Woodbury -- private communication). A reader has to know which parts of the paper are original and who should get credit for the rest. Simply rephrasing someone else's paragraph is still plagiarism. Even if you are not just being lazy by copying, but instead are just attempting to explain something well, you will irritate people by not giving credit where it is due. It's not just a matter of giving fair credit. Appropriate citations also give useful information about the history of the ideas and where a reader can learn more.

Plagiarism. An aside about extreme plagiarism. Students struggling with English often look for model sentences in papers and books. If they find sentences that serve their purposes, they might use exactly those sentences in their report. This direct copying is the most extreme form of plagiarism. It can get you expelled from school or fired from a job. As Peter Woodbury said, "If you love someone else's sentence, put it in quotations, and cite it."

N) A picture is worth a thousand words. The figures in your paper should tell your story. Even if there are just two figures, a reader should get the gist of your message by looking at just those two. As for your writing, your figures should answer the questions which would naturally come to a curious reader. And, like good writing, a figure shouldn't be a puzzle to solve, but something that explains and clarifies. 

Figures, like text, inevitably need lots of revision. It's true that "A picture is worth a thousand words". But, not usually stated is the dual aspect of this. A picture is as hard to create as are a thousand words. It is not unusual to spend a couple of days, a thousand minutes, to make and finalize a single figure.

O) Spelling, grammar, etc. Good language can't make a bad idea good. But bad language can make a good idea useless. At one extreme, really bad language is simply impenetrable, turning a sentence into a problem the reader can't solve. Less extreme, but also an issue, is the set of picky readers who know, and care too much, about the rules of writing. Those people would rather notice that you spelled 'thier' wrong than notice  that what you have written,  right t-h-e-r-e in front of t-h-e-i-r eyes, is your perfect solution to their biggest problem.They're blinded by your bad spelling into not seeing the gold that you are offering them. Picky fools. But, for better or worse, some of these picky fools will be your readers. And, unfortunately, even not-picky readers will sometimes be distracted by bad English.

Here are some of the hundreds of things that will help focus your readers attentions on your content: match a sentence's length with the complexity of the idea it expresses; use variety in vocabulary, but not by using inexact synonyms which interfere with clarity and precision; don't use SJOA (specialized jargon or acronyms); don't mix tenses or voices; and, as mentioned above, use grammar and punctuation that stay in the bounds of accepted usage. Here is a trick that catches lots of language usage errors:

read your paper out loud and make sure it sounds good to you.

But, again, don't let your concern about literary style interfere with your central goal of being clear. An editor (or literate friend) can fix your bad spelling and grammar, but no one can fix your ideas if they can't understand them.

P) Wikipedia.   Google searches and Wikipedia etc are a great place to learn things that you don't know about. And,  a great way to write a mediocre report is to paraphrase Wikipedia.  Imagine that you are  a good student at a top school, someone who  is also a good writer. Imagine that you spend a day  studying the web and writing a summary of what you read.   That makes up a pretty bad research report.  What's wrong with it?  It's not targeted enough towards your goals. It probably lacks a central question (a thesis) and therefor doesn't reveal an answer.  It doesn't show that you have your own view of the subject.

IV. Organizing your work and time

A. The structure of a paper

Here is one way to organize a paper. If you know a better one, use that instead.

1. Title page. This page should have the title, the full author list, all details about how to reach all the authors in the near and distant future, the date of the paper and of any revisions, and the context of the paper (e.g., final report for a certain class with a certain number of credits, Major and year of the student, for submission to a certain journal, etc). The title page should include anything that a random person, picking up the report 10 years in the future, would want to know about its context. To save paper, this could also be header material on the first page.

2. Abstract. This is a complete and concise summary, a restatement,  of the whole paper. It explains the context, the results and the applications. How long? Two to ten sentences and never longer than a double-spaced page. Because an abstract optimizes completeness and accuracy in a limited space, it may be dense reading. Even a good abstract may only be fully intelligible to an expert, or to someone who has already read the full paper. There's a sample abstract in item VI, below.

Answers, not questions.  The abstract should be concise answers to questions. It should not be a list of question topics. `In the summer of 2019  I went to Finland.' is a good sentence for an Abstract.  `This paper is about where I went one summer." is not. 

3. Introduction. Here you entice your readers. You bring them from what is commonly understood to the point of appreciating the questions your research answers. You introduce the ideas that led to the present work. You explain the possible applications. Keep in mind people who should be interested, but aren't yet, and what might engage them.  Most importantly, you pose the questions that the rest of the paper answers. If you start with "Since the dawn of civilization mankind has always been fascinated with X", or anything that smells like that, you have missed something that I wrote above (e.g. IIA, IIIA, IIIB).

4a. Methods and 4b. Results. In these sections you explain what you did and what you found. These are the core of the paper. You may divide them into various sections as appropriate (e.g., Model Explanation, Experimental Method, Governing Equations, Solution Method, Results, etc.). These parts of the paper should not spend too much time being philosophical, introspective or self critical.

5. Discussion. Here you discuss, critically, what you found. What are the implications? What approximations were central? What is surprising? What are possible generalizations? What natural questions does your work leave unanswered? What future work seems needed? etc. This part of the paper can, and should be, self critical.

** Note: Sections 4 & 5 above, the main presentation of your original work, might be combined into one section or divided into several sections. However you organize that central part of your report (4 & 5), use  clear headings  or subheadings to make your organization clear.**

6. Conclusion. The conclusion is a summary of the results. As opposed to the abstract, it does not need to summarize the methods and does not need to be as concise.

7. Acknowledgments. A relatively complete acknowledgment section shows courtesy to those who helped and funded you, and informs readers of your working environment. Usually one or two short sentences are enough.

8. Citations/references. A full list of the papers, texts and websites mentioned in the paper with full reference information. It is best for each listing to include the title of the book or article, unless the target journal explicitly forbids this. Every reference should have been mentioned at least once in the text.

9. Figures and captions. It is easiest for the reader if the figures and captions appear in the text and near to the text that refers to them. Only put figures at the end if a journal demands that.

10. Appendices. Here you put details that are needed for completeness but whose complete expression would interfere with the flow of your main text. These things have a place, perhaps small, in your central argument, yet are long or complex. Also at the end, you can put things you might like to keep for your records, but take too much space for a published paper. Things like computer programs, mathematical proofs, detailed graphs, work chronologies (`first I tried ...'), purchase lists, and shop drawings.

B. How should you spend your time?

Some suggestions:

1. Before you write. The initial steps.

a. Think about your message until you can say it out loud. Then do, and see if it makes sense to a friend or two.

b. Then, organize the text, somehow jotting down the essential flow within and between sections. Use a short conventional outline, a few short lists, or a diagram with ideas connected by arrows (a 'concept map'). An outline that catches the essence of the structure can free you to think about the details as you write. But an outline with too high a ratio of detail to thought can feel restrictive. I find detailed outlines more intimidating than helpful. I find it easier to let the structure evolve during editing. But others think the opposite, that your organization should be clear in your mind before you start to write. If making a detailed outline helps you, then write one. If the idea of an outline paralyzes you, keep the outline broad and vague and organize as you go. Either way can work.

c. After organizing as well as you  find useful, start writing. Write in the order that feels most natural to you. You need not write in order. Start with the conclusions if that is what comes to you first. The first draft should be as complete and accurate as possible, but not concise, polished or optimally structured. As you write, allow yourself to modify the structure, especially by putting similar ideas together. But don't let revision slow your transfer of information from mind to paper too much. Attempting to get ideas onto paper while also trying to finely hone the text can be crippling.

2. Then comes revision. Even if you are a writing genius, a scientific genius, or both, you probably have to revise. A lot. You must now go through many cycles of testing, changing, adding, deleting, and reworking.  Again and again, for hours and hours. Experienced writers will tell you that revision is 90% of the effort, or 95%, or 99% or more. But no writer  will say that revision  is 80% of the effort or less. After the uphill struggle of forming and idea and writing a first draft, revision is mostly all downhill. But it's a long glide,  it's most of the trip. When you have a decent first draft you can be satisfied that you are almost done. In a way. You only have 90% (or maybe 95% or 99%) of the work to finish up.

B. What is the best report you can write?

The perfect report is perfectly clear, perfectly convincing, perfectly interesting, perfectly blah blah blah. But you don't know what that is or how to get there. What you can do is make your present draft less bad.  You can find ways to put similar ideas closer together, to make sentences more clear, to make the central ideas more prominent, to make the text more smooth, to remove unneeded repetition, to remove unrelated ideas, etc. When you can't find a flaw, or if all attempts to fix the flaws that you have found are not improvements, then that is the best report you can write. Do you want to do better than that? Then you need to know things about writing that I don't know.  The best report you can write is one that you can't find a way to improve.

V. Final comments

My apology. As Pascal said in 1657, "I'm sorry this letter is so long. I didn't have time to write a shorter one." After at least 70 hours of writing, reading, and revising, I could still make this essay shorter, and better in other ways, by following more of my own advice. But advice is cheap. I'm a fat sloppy guy explaining how to be trim and fit. And, while I am apologizing,  I am sorry that  there are all those great bits of advice about good style that are simply over my head. So they are not here. Sorry again.

Want more advice? After a few drafts of this essay I was pointed to this 1985 how-to guide by Marc Raibert, the guy who got me into robots. I like his tone and what he says. Here is another one, much in the spirit of this one. Devin Jindrich, another locomotion person, developed a whole www site to help you use writing to help your thinking: Reasoning and Writing for Science.  Guy Hoffman has a good essay about the structure of a good paper, with lots of tips and also references where you can find more writing advice.

********
Please check the check list. This is a request to my students: Please consider Sections III ("Sixteen things ...") and IV.A ("The structure of a paper"), above, as a check list. Do your best at each element. When you think your report is done, go down those lists again and change your paper until you  are not subject to the criticisms listed and you have a paper that is appropriately structured.
*******

Thanks to Steve Collins for provoking this essay and then, eventually, helping to tune it up.  And to Rachel Ruina whose story about how to teach writing to second graders is its core. Also, to Saskya van Nouhuys, Dave Nutter, Hermann and Barbara Riedel, Peter Woodbury, Steven Youra, Dirk van Nouhuys, Sidney Orlov, Rudra Pratap, Marcia Poulsen, Tomomi Ueda, Seppo Korpela, Manoj Srinivasan, Javad Hasaneini, Atif Chaudhry, Betta Fisher, Devin Jindrich and Matias Waller, and others who I have undoubtedly forgotten,  for criticisms and for suggested additions, deletions, and reorganization that helped make this essay little resemble its first draft.

APPENDICES

VI. Sample abstract

Here is an abstract that Manoj Srinivasan and I wrote. We got fan mail about this from ever-critical Art Kuo, "This is perhaps the most concise, clear, and beautifully written abstract I've ever read. It's a poem. ...The success of your soda can abstract is that each sentence moved you forward, it told essentially a complete story from motivation to main finding, and it did it all in remarkably few words."  I don't know what drugs he was taking, but I'd like some.

Title: Rocking and rolling: a can that appears to rock might actually roll.
Abstract:
`A beer bottle or soda can on a table, when slightly tipped and released, falls to an upright position and then rocks up to a somewhat opposite tilt. Superficially this rocking motion involves a collision when the flat circular base of the container slaps the table before rocking up to the opposite tilt. A keen eye notices that the after-slap rising tilt is not generally just diametrically opposite the initial tilt but is veered to one side or the other. Cushman and Duistermaat [Regular Chaotic Dyn. 11, 31 (2006)] recently noticed such veering when a flat disk with rolling boundary conditions is dropped nearly flat. Here, we generalize these rolling disk results to arbitrary axi-symmetric bodies and to frictionless sliding. More specifically, we study motions that almost but do not quite involve a face-down collision of the round container's bottom with the tabletop. These motions involve a sudden rapid motion of the contact point around the circular base. Surprisingly, similar to the rolling disk, the net angle of motion of this contact point is nearly independent of initial conditions. This angle of turn depends simply on the geometry and mass distribution but not on the moment of inertia about the symmetry axis. We derive simple asymptotic formulas for this "angle of turn" of the contact point and check the result with numerics and with simple experiments. For tall containers (height much bigger than radius) the angle of turn is just over pi and the sudden rolling motion superficially appears as a nearly symmetric collision leading to leaning on an almost diametrically opposite point on the bottom rim.'

Of course when Manoj and I read it now, we see how to make it clearer. For example, the key idea, that what looks like a slipping collision is really an extremely fast rolling motion, isn't prominent enough. We didn't revise, revise, and revise again, enough times!

VII. Rejects: my writing gems

Here are some fragments I worked on and, at least at some point, liked. But later when revising I thought they were redundant, off-topic, distracting or otherwise bad. So I edited them out. I really shouldn't show them to you. But, I want you to see what beautiful things I threw away so you will feel better about throwing things out yourself.

Marc Raibert suggests titling a section of your paper "My Writing Gems". Then put your formerly-wonderful, but now deleted text, there. Then save that. in a special private place. This supplements "kill your darlings" with "and bury them in a special graveyard."

My writing gets good only after I have worked on it a lot.

The main reason to write is to move a collection of facts and ideas into someone else's head.

Communication, in writing or otherwise, is transmission of information. Because your readers probably don't have extrasensory perception, writing can only convey content by having it. The quality of writing cannot transcend the quality of the information being transmitted.

This evolutionary process is sufficient, if not efficient,

Many teachers are also off track this way, having been trained in the same system. Us teachers too-often grade by an abstract image we hold of "good writing" as defined by adherence to various guidelines (spelling, grammar, topic sentences, fancy words etc.), not by success at transmitting information.

Your readers will likely pick up on whether you are writing to sound good or to get something across.

Much as we hope or pretend that they would, the exceptions to these truths don't negate their core validity. Writing just is more grinding than freeform conceptualization, both for an experienced story teller and for you and I.

The image of the talented skilled writer dashing off something lucent and concise, like puzzle pieces falling out of a box pre-assembled, is probably a fantasy twice over. First, it probably rarely happens. Second, when it does happen it probably doesn't happen. Einstein's paper on the theory of relativity is said to be great, and maybe he did not write 20 drafts of it. But I guess he worked and worked to organize the ideas in his head, not just the basic science, but how he was going to communicate his ideas. He probably had to do his 95% to 99% of perspiration, just like the rest of us. If ever there was a writer who had the talent and practice to do less editing it was the author of The Elements of Style, E. B. White. But his classic story Charlotte's Web has eight known drafts, and maybe there were more.

You should respect your reader's free will.

Your paper is a treasure map. It should tell your reader what valuable thing they can find, and it should show them how to find it.

Imagine a completed jigsaw puzzle where someone left in a piece that belonged to a different puzzle!

Your opponents are all the possible other ideas out there in the universe that are not what you are trying to get across.

The repeated testing and selecting of written ideas is editing.

As William Zinsser said "The essence of writing is rewriting."