Student writing tips

This advice is aimed at masters and PhD students in STEM, who are writing their first few reports and papers in English. Some of the advice is specific to quantum information, some is specific to LaTeX, some to German natives speakers, but most is pretty general. I’m writing this as found myself repeating the same advice to generations and generations of students, before and after reading their drafts.

1. Read books. Read books by native English speakers: novels, YA, sci-fi, fantasy, history, fiction and non-fiction, comics. Start with whatever genre you like. This is how you build intuition for grammar, story structure and vocabulary. Reading is mandatory.
2. Read a style guide. Not as a prescriptive rulebook, but as an example of how people find conventions. I like the Guardian style guide, for example (follow that link for that vs which, a common hiccup for German-speaking students; check also H for half and hyphen).
3. LaTeX macros and packages. Ask your supervisor if they have a file of macros and template they normally use; eventually you’ll want to write papers with them, and it’s easier if they don’t have to adapt to your macros. You can also download the source code of one of their recent papers from the arXiv and take the macros from there. (Still, I’d ask first, just in case they didn’t write that particular paper.) You may still decide that their conventions are a hot mess and want to define your macros from scratch, but it’s good to check first, as you’ll have to explain them how to use your commands.
4. Decide who your target reader is. Ask your supervisor: whom am I writing for, what background can I assume? For student projects that I supervise, this is “the student who’ll come after you to follow up on your work, or on a related topic.” That is: someone who knows as much as you did when you started the project (for example, someone who took one or two quantum information courses but knows nothing on your specific topic). You have probably done a thorough bibliographic research to get the basics of the topic of your project; please include a review of the topic with all these basics needed to understand your work. This way the next student can read your report in a self-contained way, and it can be the first step towards their building up on your results. As a nice side effect, if the review part of the project is very good, it may be useful for other people and sometimes it can be published independently. Now, of course this doesn’t necessarily hold if you are writing a paper aimed at experts, so ask your supervisor.
5. Formulas are part of the sentence. As such, they require punctuation, even if they are in their own line. For example, now we show that 2 = 1 + 1, and also
   4 = 2 + 2,
   3 = 2 + 1.
   Note how I didn’t write “we show that: ” with a colon, just as I wouldn’t write “we show that: pigs don’t fly.”
6. Have a running example. Especially if your work has many definitions and abstract results, have an easy, intuitive, grounding example from the beginning helps the reader follow what (and why) you’re developing the framework in a certain way. Every time you have a new result or definition, show us how it applies to the example. This is doubly important for talks. Take the simplest example you can find that still shows what’s interesting about your approach: an ideal gas, a couple of qubits, Alice and Bob sending an encrypted letter, the picture of a cat.
7. Intuitions before definitions. See above. Give the reader a reason to care about the upcoming definition; usually best done through examples, but sometimes you can find another way to frame it.
8. Shorter sentences. Yes, all rules are made to be broken, but if you routinely have four-line sentences, you have a problem. Read each paragraph and see if it’s easy to parse the sentence. Long sentences are ok if they’re parsed sequentially, that is if the reader doesn’t have to keep the whole thing in their memory in order to process the meaning of the sentence.
9. Name your people. It is just so much easier to read, say, a cryptographic protocol between Alice and Bob than between agents A1 and A2. You can stay abstract in the definitions and theorems, but for examples and explanatory text between formal math environments, name your agents, and stick to those names throughout the document. It doesn’t need to be the standard Alice, Bob, Charlie and Eve, and it’s refreshing to see more diverse examples; just be consistent after you’ve introduced them for the first time. Pro-tip: if you have two agents interacting often it helps if they have different pronouns, so that it’s unambiguous whom you’re referring to, without always having to write their names (“after Alice sends him the qubit, Bob measures it and announces the basis choice through their public authenticated channel”).
10. Don’t default to “him”. Few things are more annoying than reading a paper where the writer is always referring to an abstract physicist, experimenter, or even the reader, as “him”. There’s a fascinating historical and cultural context to why this is annoying (a long tradition of taking STEM as the default domain of men), but you’re probably more interested in knowing how to avoid making your readers feel excluded and alienated. You have two options: use the gender-neutral singular they (“after the physicist measures the qubit, they have to process the outcome classically”), or use a variety of pronouns throughout the document. For example, “an observer may wonder what the state of the qubit was before she measured it” and later in a new section “the agent may try to decode the message he received” or “we can now make an educated guess for the final state.” These hypothetical placeholder scientists that only come up once don’t need to be named, though there’s nothing wrong with doing so. “We” is such a nice pronoun: it makes the reader feel included in your journey of discovery.
11. Get to the point. Tell us what you’re going to achieve in the document within the first two sentences. There is time to motivate it and give the big picture right after, but an expert reader (like your supervisor or a referee) will want to know immediately what your results are. Often this can be done by putting the abstract up front. If for some reason that’s not possible, start the introduction with this.
12. Hunt and destroy weasel words. Read the wikipedia article on this. Half of my comments on student drafts are just scratching out “importantly”, “scientists think” and “it is trivial to show” bits. Show, don’t tell.
13. Take care of your bibliography. This may sound like nitpicking but it’s actually mandatory for any publication venue, so the sooner you get this right, the least painful it will be in the long run. All published articles cited need clickable DOI links (use \doi in your bib file — you’re using a bib file, right?). As a matter of courtesy to the reader, include clickable links to all possible references (arXiv, talk recordings, conference website, publisher page for books, GitHub repo, author’s website for lecture notes). If you want to preserve upper case letters inside a title, use curly brackets: \title{A summary of {L}\’idia’s opinions on style}. If possible, follow the same naming convention throughout the bibliography, for instance on whether to show the full names of authors or just their family name (careful there, as conventions vary around the globe). Personally I prefer to go with the way the authors put it on their paper; it just shouldn’t be arbitrary due to the quirks of the software you used to import the bib reference. Check authors’ preferences for the spelling of their names (you can compare the compiled version of your bibliography to the way their names are written on the arXiv or journal).
14. Figure captions should stand on their own. We like to think that readers will patiently take our hand and read our papers from the introduction to the conclusions. In practice, most readers will read the abstract and then skim the paper, looking first at the pictures and reading their captions. Therefore, the captions should give them enough information to understand the picture (within reason). So don’t just write “Fig. 1) Example of the key distribution protocol” in the caption and leave the description only in the main text, say “Fig. 1) Key distribution protocol: Alice prepares a qubit in one of four states (…) ” .
15. More pictures. Whenever something takes many words to explain, try also showing it with a picture. This will help give an intuition of what your maths are trying to express, and you can reuse the figures to explain things quickly in a talk. Some things are obvious to draw: the setting of an experiment, the architecture of a neural network, a quantum circuit, a space-time diagram. But abstract concepts can also benefit from this, for instance when you have a series of maps between different spaces (think of the Stinespring dilation, for a simple example), it can help to have a picture where each space is a square, demonstrating the inclusions, and the map is drawn as arrows. Sometimes it seems impossible to draw a very formal definition or result, but you can still draw how it applies to your running example. The drawing style doesn’t matter, as long as it’s clear. You can have a first shot just taking a photo of a hand-drawn sketch to get your supervisor’s ok before you invest too much in it.
16. Run pictures by a colour blindness simulator. Do this for the final version of your pictures: there are many colourblind researchers, and you want your figures to be accessible. In addition, consider that some people still print papers, so make them toner-friendly by avoiding large shaded areas and make the pictures readable in black-and-white. For example, if your plot has lines of different colours and that’s important, make sure they also have different dash patterns or thickness. If you must have very colour-heavy figures that may eat up someone’s toner, one option is to put them all on the same page (without normal text in it) and add a footnote to that effect, so that people can skip that page when printing. In general: use colour in papers like you’d use perfume on a night out: a little can be nice and give some flair, but don’t overdo it, don’t rely on it to convey important information, and don’t use it to hide poor (picture) hygiene issues.
17. Lídia Hates Camel Case. Others disagree. Don’t feel pressured to follow my pet peeve. To me, a title or section title in camel case is saying This Text Is Not That Interesting So I Need Big Letters To Get Your Attention.
18. Lídia hates double column. It’s just super impractical to read on screens. If you’re my student, please use single column. [Edit: if you like reading papers on your phone or on small screens, use the arXiv Vanity, which converts arXiv papers to responsive html. It’s better than scrolling down, then right, then up again, which you do if you try to read it in double column.] [Second edit: dear student, sooner or later you will find out that researchers have strong opinions on single vs double column, with both sides providing reasonable, irrefutable arguments. It’s like a spontaneous symmetry break. The best way to survive this until you’re senior enough to have your own stubborn opinion and can impose it on your coauthors (one of the privileges of being around for a while) is to ask your supervisor what they prefer, and roll with that.]
19. LaTeX spacing peculiarities. Use ~ before \cite, \ref and after periods that are not full stops, e.g.~\cite{this}, i.e.~you know what I mean, as shown in Fig.~\ref{fig:that}. This makes sure the thing before and after the ~ are in the same line and with a standard space between them, and not the long space that comes after a full stop. You can also use e.g.\ just a backslash, if you don’t necessarily want them in the same line and only care about the spacing (but for references you want them in the same line). Use \dots, not … .
20. Informative table of contents. If your report or paper has more than a handful of pages, add a clickable table of contents before or after the introduction. At the very least, detail the structure of the document at the end of the introduction. It’s not a mystery thriller, let us know where you are going.
21. Notation table. If your report is interdisciplinary (for example, a project on relativity for a quantum information group), include a table of notation at the start. If it becomes a paper, you can move the table to the appendix.

Thanks: Some of this advice I picked up over the years from here and there, and I’ll add references here as I recall them. Thanks to everyone who sent comments that made it to the list: Johan “we” Åberg , Nuriya “spoilers” Nurgalieva, Ernest “spacing” Tan, Sabine “toner” Hossenfelder and Bruno “punctuation” Montalto.
Thanks also to people who have given me advice specific to papers, like Howard “a paper is a story” Wiseman and Sandu “one idea, one paper” Popescu, and advice about the backend of writing papers, like Eloísa “one bib to rule them all” Grifo and Matt “but not a super large bib” Leifer (see below).

Disclaimers:

1. Because this is specifically about writing and the presentation of your report from the perspective of the reader, I’ve left out backend matters: how to organise your macros (I have a file called packages.tex and another called macros.tex that I bring to every paper) and bibliography (a master .bib file to rule them all, in my case), or how overleaf is the best thing since sliced bread for collaborative paper writing (git is best left for software).
2. There is also very good advice for papers that doesn’t necessarily apply to student reports: this is because student projects are limited to a fixed time window, while a paper tells a single story. For example, a report shows what you’ve achieved in six months, and from there 0-2 papers can stem, depending on how many self-contained stories one can extract from that. By the way, that number means very little in terms of your abilities as a researcher! Research is unpredictable, and sometimes it takes a few more months after the project to find results worth publishing, or the conclusion may be “we don’t have the tools to tackle this topic for now”, and that’s all valid.